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
    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"

Attachments available at this configuration scope.

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"

Provider configuration is now expressed through the polymorphic Model field. The previous Config core.ProviderConfig field has been removed. 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

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

Model selects which LLM model to use. Supports two forms:

• string: a model ID to be resolved via the ResourceStore (e.g. "openai-gpt-4o-mini")
• object: an inline core.ProviderConfig with provider/model/params

During compile/link, string refs are resolved and merged with inline fields following project precedence rules. Defaults are filled from the project when neither ref nor inline identity is provided.

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

Attachments available at this configuration scope.

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

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