aion.yaml Configuration

Complete Example

This example shows a fully formed aion.yaml with multiple agents, skills, and typed agent configuration.

aion:
  agents:
    support:
      path: "./agents/support.py:build_graph"
      name: "Support Agent"
      description: "Customer support assistant"
      version: "1.2.0"
      input_modes: ["text", "json"]
      output_modes: ["text", "json"]
      enabled_extensions:
        - "https://docs.aion.to/a2a/extensions/aion/daemon/1.0.0"
      skills:
        - id: "ticket_search"
          name: "Ticket Search"
          description: "Search historical support tickets"
          tags: ["support", "search"]
          examples:
            - "Find similar tickets for login issues"
      configuration:
        response_style:
          type: "string"
          default: "concise"
          required: true
          enum: ["concise", "detailed"]
        ticketing_api_key:
          type: "secret"
          required: true
        model:
          type: "llm"
          default: "openai/gpt-4.1-mini"
          required: true
        max_retries:
          type: "integer"
          default: 3
          min: 0
          max: 10
        include_internal_notes:
          type: "boolean"
          default: false

    onboarding:
      path: "my_project.onboarding:create_agent"

  mcp:
    port: 9000

Root Structure

aion:
  agents:
    your_agent_id:
      path: "./agent.py:build_graph"

aion.yaml must include the top-level aion key and an agents map.

Unknown Keys Are Rejected

aion serve fails on a key it does not recognize and names it, rather than ignoring it. A key that is dropped silently reads as supported for as long as nobody checks what the server did with it, so every setting below is one the SDK acts on, and anything else is a typo the startup will point at.

Configuration validation failed
Unknown key 'agents -> support -> capabilties' in aion.yaml.
Known keys at this level: configuration, description, enabled_extensions,
input_modes, name, output_modes, path, skills, version

Configuration Settings

Setting	Required	Description
`aion.agents`	yes	Map of agent IDs to agent configuration blocks.
`aion.agents.<agent_id>.path`	yes	Import target (`module_or_file[:symbol]`) for agent discovery.
`aion.agents.<agent_id>.skills`	no	Skill metadata surfaced in agent card output.
`aion.agents.<agent_id>.configuration`	no	Typed configuration schema exposed via configuration metadata.
`aion.mcp.port`	no	Local port of an MCP server to proxy. Sets up the `/mcp` mount; without it, nothing is mounted. See aion-mcp.

Required Field

Field	Type	Description
`path`	string	Import path to the agent object or factory function.

Common Optional Fields

Field	Type	Default	Notes
`name`	string	`Agent`	Agent display name in card metadata.
`description`	string	empty	Human-readable summary.
`version`	semver string	`1.0.0`	Format `X.Y.Z`.
`input_modes`	string[]	`["text/plain"]`	Media types the agent accepts, such as `image/png` or `image/`. The short names `text`, `json`, `image`, `audio` and `video` stand for `text/plain`, `application/json`, `image/`, `audio/` and `video/`. The agent card lists them as media types.
`output_modes`	string[]	`["text/plain"]`	Media types the agent answers with; written as `input_modes`.
`enabled_extensions`	string[]	`[]`	A2A extension URIs to activate for this agent. Use this to opt in to extensions that are inactive by default: daemon, and any custom extensions.

Path Patterns

path accepts module_or_file[:symbol].

Pattern	Example	Behavior
File path + symbol	`./agent.py:build_graph`	Loads a file module, then resolves the named symbol.
File path auto-discovery	`./agent.py`	Loads a file module, then auto-discovers a supported object.
Dotted module + symbol	`my_project.agent:create_agent`	Imports module from `PYTHONPATH`, then resolves symbol.
Dotted module auto-discovery	`my_project.agent`	Imports module, then auto-discovers a supported object.

Auto-discovery prefers framework instances over classes when both are present. Factory functions should be explicitly named with :symbol because callables are not selected by auto-discovery.

Skills

skills:
  - id: "web_search"
    name: "Web Search"
    description: "Search external data sources"
    tags: ["search", "research"]
    examples:
      - "Find recent AI platform announcements"

Enabled Extensions

Use enabled_extensions to opt in to A2A extensions that are inactive by default. Protocol-level extensions (distribution, traceability, messaging, event, cards) are always active and do not need to be listed here. The daemon extension activates only when specified — add it here for daemon-scoped agents.

enabled_extensions:
  - "https://docs.aion.to/a2a/extensions/aion/daemon/1.0.0"

Each entry is a full extension URI. The extension must have a registered descriptor in the Aion extension registry — unrecognised URIs are silently ignored.

Agent Configuration

Use configuration to define the schema by which an agent can be configured. This schema is represented in the Aion control plane so a deployer can set values for each deployment context. The configured values are provided to the agent on each request. This allows the same agent implementation to run in multiple environments with different configuration variables.

configuration:
  temperature:
    type: "float"
    default: 0.7
    min: 0.0
    max: 2.0

Supported field types:

string
secret
llm
integer
float
boolean
array
object

Common Field Properties

These properties are shared by agent-configuration field types. Type-specific sections below describe additional constraints and nested schema properties.

Property	Type	Required	Description
`type`	string	yes	Field type (`string`, `secret`, `llm`, `integer`, `float`, `boolean`, `array`, `object`).
`description`	string	no	Human-readable field description.
`default`	any	no	Literal default when supported by the field type; not valid for `secret`.
`required`	boolean	no	Whether the field must be provided.
`nullable`	boolean	no	Whether `null` is allowed.

String Fields

Property	Type	Description
`min_length`	integer	Minimum character length.
`max_length`	integer	Maximum character length.
`enum`	string[]	Allowed values list.

Example:

configuration:
  region:
    type: "string"
    description: "Deployment region"
    default: "us-east-1"
    required: true
    min_length: 3
    max_length: 32
    enum: ["us-east-1", "eu-west-1"]

Secret Fields

Use type: "secret" for a top-level configuration value that must be encrypted at rest. Composer provides a write-only input and does not display the saved value.

configuration:
  ticketing_api_key:
    type: "secret"
    description: "Ticketing provider API key"
    required: true

Secret fields support the common description, required, and nullable properties. They cannot define default, min_length, max_length, enum, or items, and they cannot appear inside arrays or objects. At runtime, secret values are provided to the agent as ordinary strings. When Aion calls a remote server, these values are included as plaintext in the configuration map carried by the Distribution extension or Daemon extension. Treat these payloads as sensitive data. Do not log, persist, or forward their configuration values beyond the intended runtime.

LLM Fields

LLM fields store a model ID string, but the Aion control plane can render them as a single-select model picker. The selectable model list is populated from the models available through the control plane’s model service rather than from a static enum in aion.yaml. Use an llm field when the agent will invoke the Aion model service and should let deployers choose which supported model to use. The configured value is still provided to the agent as an environment configuration value, so agent code must pass that selected model ID into the SDK model-service call. Example:

configuration:
  model:
    type: "llm"
    description: "Model used for support replies"
    default: "openai/gpt-4.1-mini"
    required: true

Integer Fields

Property	Type	Description
`min`	integer	Inclusive minimum value.
`max`	integer	Inclusive maximum value.
`enum`	integer[]	Allowed integer values list.

Example:

configuration:
  max_retries:
    type: "integer"
    default: 3
    min: 0
    max: 10

Float Fields

Property	Type	Description
`min`	number	Inclusive minimum value.
`max`	number	Inclusive maximum value.
`enum`	number[]	Allowed floating-point values list.

Example:

configuration:
  temperature:
    type: "float"
    default: 0.7
    min: 0.0
    max: 2.0

Boolean Fields

Boolean fields use common properties only. Example:

configuration:
  enable_streaming:
    type: "boolean"
    description: "Enable streaming responses"
    default: true

Array Fields

Property	Type	Description
`min_length`	integer	Minimum array item count.
`max_length`	integer	Maximum array item count.
`items`	object	Schema describing each array item.

Example:

configuration:
  supported_languages:
    type: "array"
    min_length: 1
    max_length: 20
    items:
      type: "string"
      enum: ["en", "es", "fr", "de"]
    default: ["en"]

Object Fields

Property	Type	Description
`items`	object	Map of property names to nested field schemas.

Example:

configuration:
  model_config:
    type: "object"
    required: true
    items:
      model_name:
        type: "string"
        default: "gpt-4"
      max_tokens:
        type: "integer"
        default: 4000
        min: 100
        max: 8000
      use_cache:
        type: "boolean"
        default: true

Framework Notes

path must resolve to an object the installed adapter recognises:

Framework	`path` resolves to	Install
LangGraph	A `StateGraph`, a compiled `Pregel`, or a callable returning one.	`aionto-sdk[langgraph-server]`
Google ADK	A `BaseAgent`, or a callable returning one.	`aionto-sdk[adk-server]`

The adapter that recognises the object runs the agent, so an agent needs the extra for the framework it is written in.

Multi-Agent Example

aion:
  agents:
    support:
      path: "./support.py:build_graph"

    onboarding:
      path: "./adk_agent.py:create_agent"

​Complete Example

​Root Structure

​Unknown Keys Are Rejected

​Configuration Settings

​Required Field

​Common Optional Fields

​Path Patterns

​Skills

​Enabled Extensions

​Agent Configuration

​Common Field Properties

​String Fields

​Secret Fields

​LLM Fields

​Integer Fields

​Float Fields

​Boolean Fields

​Array Fields

​Object Fields

​Framework Notes

​Multi-Agent Example

Complete Example

Root Structure

Unknown Keys Are Rejected

Configuration Settings

Required Field

Common Optional Fields

Path Patterns

Skills

Enabled Extensions

Agent Configuration

Common Field Properties

String Fields

Secret Fields

LLM Fields

Integer Fields

Float Fields

Boolean Fields

Array Fields

Object Fields

Framework Notes

Multi-Agent Example