Agent Schema

Structured actions the agent can perform with defined input/output schemas. Actions provide type-safe interfaces for specific agent capabilities.

Example:

actions:
  - id: "review-code"
    prompt: |
      Analyze code {{.input.code}} for quality and improvements
    json_mode: true
    input:
      type: "object"
      properties:
        code:
          type: "string"
          description: "The code to review"
    output:
      type: "object"
      properties:
        quality:
          type: "string"
          description: "The quality of the code"

LLM provider configuration defining which AI model to use and its parameters. Supports multiple providers including OpenAI, Anthropic, Google, Groq, and local models.

Required fields: provider, model Optional fields: api_key, api_url, params (temperature, max_tokens, etc.)

Environment variables available during agent execution. Used for configuration, secrets, and runtime settings.

Example:

env:
  API_KEY: "{{.env.OPENAI_API_KEY}}"
  DEBUG_MODE: "true"

Unique identifier for the agent within the project scope. Used for referencing the agent in workflows and other configurations.

• Examples: "code-assistant", "data-analyst", "customer-support"

System instructions that define the agent's personality, behavior, and constraints. These instructions guide how the agent interprets tasks and generates responses.

Best practices:

• Be clear and specific about the agent's role
• Define boundaries and ethical guidelines
• Include domain-specific knowledge or constraints
• Use markdown formatting for better structure

Forces the agent to always respond in valid JSON format. When enabled, the agent's responses must be parseable JSON objects.

Use cases:

• API integrations requiring structured data
• Automated processing of agent outputs
• Ensuring consistent response formats

⚠️ Note: May limit the agent's ability to provide explanatory text

Maximum number of reasoning iterations the agent can perform. The agent may self-correct and refine its response across multiple iterations to improve accuracy and address complex multi-step problems.

Default: 5 iterations

Trade-offs:

• Higher values enable more thorough problem-solving and self-correction
• Each iteration consumes additional tokens and increases response latency
• Configure based on task complexity, accuracy requirements, and cost constraints

Model Context Protocol (MCP) server configurations. MCPs provide standardized interfaces for extending agent capabilities with external services and data sources through protocol-based communication.

Common MCP integrations:

• Database connectors (PostgreSQL, Redis, MongoDB)
• Search engines (Elasticsearch, Solr)
• Knowledge bases (vector databases, documentation systems)
• External APIs (REST, GraphQL, gRPC services)

MCPs support both stdio and HTTP transport protocols.

Memory references enabling the agent to access persistent context. Memory provides stateful interactions across workflow steps and sessions.

Configuration format:

memory:
  - id: "user_context"           # Memory resource ID
    key: "user:{{.user_id}}"     # Dynamic key with template
    mode: "read-write"           # Access mode (default: "read-write")

Access modes:

• "read-write": Full access to read and modify memory
• "read-only": Can only read existing memory entries

Resource identifier for the autoloader system (must be "agent"). This field enables automatic discovery and registration of agent configurations.

Tools available to the agent for extending its capabilities. When tools are defined, the agent automatically has toolChoice set to "auto", enabling autonomous tool selection and invocation during task execution.

Tool types supported:

• File system operations (read, write, list)
• API integrations (HTTP requests, webhooks)
• Data processing utilities (parsing, transformation)
• Custom business logic (TypeScript/JavaScript execution)

Tools are referenced by ID and can be shared across multiple agents.

Default input parameters passed to the agent on every invocation. These values are merged with runtime inputs, with runtime values taking precedence.

Use cases:

• Setting default configuration values
• Providing constant context or settings
• Injecting workflow-level parameters

Unique identifier for the action within the agent's scope. Used to invoke specific actions programmatically.

• Examples: "analyze-code", "generate-summary", "validate-data"

JSON Schema defining the expected input parameters for this action. Enables validation and type checking of inputs before execution.

If nil, the action accepts any input format without validation.

Schema format: JSON Schema Draft 7

Forces JSON-formatted output for this specific action. When true, the agent must return valid JSON that conforms to the output schema.

Note: If an OutputSchema is defined, JSON mode is automatically enabled.

⚠️ Trade-off: Enabling JSON mode may limit the agent's ability to provide explanatory text or reasoning alongside the structured output.

JSON Schema defining the expected output format from this action. Used for validating agent responses and ensuring consistent output structure.

If nil, no output validation is performed.

Schema format: JSON Schema Draft 7

Detailed instructions for the agent when executing this action. Should clearly define the expected behavior, output format, and any constraints.

Best practices:

• Be specific about the desired outcome
• Include examples if complex formatting is required
• Define clear success criteria
• Specify any limitations or boundaries

Default parameters to provide to the action. These are merged with runtime parameters, with runtime values taking precedence.

Use cases:

• Setting default configuration options
• Providing constant context values
• Pre-filling common parameters