Writing the Manifest

The manifest defines what your Trik can do and how it communicates with agents.

Complete Example

Here’s the manifest for an article search trik with multiple actions:


{
  "schemaVersion": 1,
  "id": "demo/article-search",
  "name": "Article Search",
  "description": "Search and retrieve articles with session support.",
  "version": "2.0.0",
 
  "actions": {
    "search": {
      "description": "Search for articles by topic",
      "responseMode": "template",
      "inputSchema": {
        "type": "object",
        "properties": {
          "topic": { "type": "string", "minLength": 1 }
        },
        "required": ["topic"]
      },
      "agentDataSchema": {
        "type": "object",
        "properties": {
          "template": { "type": "string", "enum": ["success", "empty", "error"] },
          "count": { "type": "integer" },
          "topic": { "type": "string", "enum": ["AI", "technology", "science", "health"] },
          "articleIds": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["template"]
      },
      "responseTemplates": {
        "success": { "text": "I found {{count}} articles about {{topic}}." },
        "empty": { "text": "I couldn't find any articles about {{topic}}." },
        "error": { "text": "Something went wrong while searching." }
      }
    },
    "details": {
      "description": "Get article details by ID or reference",
      "responseMode": "passthrough",
      "inputSchema": {
        "type": "object",
        "properties": {
          "articleId": { "type": "string" },
          "reference": { "type": "string" }
        }
      },
      "userContentSchema": {
        "type": "object",
        "properties": {
          "contentType": { "type": "string", "enum": ["article"] },
          "content": { "type": "string" },
          "metadata": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "articleId": { "type": "string" }
            }
          }
        },
        "required": ["contentType", "content"]
      }
    }
  },
 
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000,
      "maxHistoryEntries": 10
    }
  },
 
  "limits": {
    "maxExecutionTimeMs": 5000
  },
 
  "entry": {
    "module": "./graph.js",
    "export": "default"
  }
}

Step-by-Step Guide

1. Identity


{
  "schemaVersion": 1,
  "id": "@yourname/my-trik",
  "name": "Human Readable Name",
  "description": "One sentence description.",
  "version": "1.0.0"
}

ID format: @publisher/name or publisher/name

2. Define Actions

Each action is an operation your Trik supports:


{
  "actions": {
    "actionName": {
      "description": "What this action does",
      "responseMode": "template",
      // schemas...
    }
  }
}

3. Choose Response Mode

Template mode - Agent sees structured data:


{
  "responseMode": "template",
  "agentDataSchema": { ... },
  "responseTemplates": { ... }
}

Passthrough mode - Content goes to user only:


{
  "responseMode": "passthrough",
  "userContentSchema": { ... }
}

4. Define Input Schema

What the agent can send:


{
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query",
        "minLength": 1
      },
      "limit": {
        "type": "integer",
        "default": 10,
        "minimum": 1,
        "maximum": 100
      }
    },
    "required": ["query"]
  }
}

Tip: Add description to help the agent use the field correctly.

5. Define Output Schemas

For template mode - agentDataSchema:


{
  "agentDataSchema": {
    "type": "object",
    "properties": {
      "template": {
        "type": "string",
        "enum": ["success", "error"]
      },
      "count": { "type": "integer" },
      "category": {
        "type": "string",
        "enum": ["news", "blog", "docs"]
      }
    },
    "required": ["template"]
  }
}

For passthrough mode - userContentSchema:


{
  "userContentSchema": {
    "type": "object",
    "properties": {
      "contentType": {
        "type": "string",
        "enum": ["article", "document"]
      },
      "content": { "type": "string" },
      "metadata": {
        "type": "object",
        "properties": {
          "title": { "type": "string" }
        }
      }
    },
    "required": ["contentType", "content"]
  }
}

6. Write Response Templates

For template mode, define pre-filled responses:


{
  "responseTemplates": {
    "success": {
      "text": "Found {{count}} results in {{category}}."
    },
    "error": {
      "text": "Search failed. Please try again."
    }
  }
}

Use {{fieldName}} for placeholders. The template field in agentData selects which template to use.

7. Configure Capabilities


{
  "capabilities": {
    "tools": [],
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000,
      "maxHistoryEntries": 10
    }
  }
}

8. Set Limits


{
  "limits": {
    "maxExecutionTimeMs": 5000
  }
}

9. Configuration Requirements (Optional)

Declare required configuration values (API keys, tokens):


{
  "config": {
    "required": [
      { "key": "API_KEY", "description": "Your API key for the service" }
    ],
    "optional": [
      { "key": "WEBHOOK_URL", "description": "Optional webhook URL", "default": "" }
    ]
  }
}

The gateway validates required config values are set before executing the trik.

Schema Design Tips

Use Enums for Safety


// Good: constrained values
"status": {
  "type": "string",
  "enum": ["success", "pending", "error"]
}
 
// Bad: free-form string
"status": { "type": "string" }

Provide Descriptions


"topic": {
  "type": "string",
  "description": "The topic to search for. Examples: 'machine learning', 'climate change'",
  "minLength": 2
}

Use Appropriate Types


// Counts
"resultCount": { "type": "integer", "minimum": 0 }
 
// IDs
"articleId": { "type": "string", "pattern": "^art-[0-9]+$" }
 
// Booleans
"isAvailable": { "type": "boolean" }

Validation

The gateway validates all inputs and outputs against your schemas. Invalid data is rejected with an error.

Test your schemas:


# Validate manifest
trik validate ./manifest.json
 
# Test with sample input
trik test ./manifest.json --action search --input '{"topic": "AI"}'

Next: Learn about Building the Graph.