aion.yaml Configuration

Complete Example

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

aion:
  agents:
    support:
      path: "./agents/support.py:build_graph"
      framework: "langgraph"
      name: "Support Agent"
      description: "Customer support assistant"
      version: "1.2.0"
      input_modes: ["text", "json"]
      output_modes: ["text", "json"]
      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"
      framework: "adk"

  http:
    /api/custom: "my_project.web:create_fastapi_app"

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.

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>.framework`	no	Framework adapter selection (`langgraph` or `adk`).
`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.http.<mount_path>`	no	Optional dynamic ASGI/FastAPI app mounts on the agent server.

Required Field

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

Common Optional Fields

Field	Type	Default	Notes
`framework`	`langgraph` or `adk`	`langgraph`	Runtime adapter target.
`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"]`	Allowed: text, audio, image, video, json.
`output_modes`	string[]	`["text"]`	Allowed: text, audio, image, video, json.

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"

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

LangGraph paths should resolve to a graph instance or graph factory function.
ADK paths should resolve to a BaseAgent instance or factory function.

Multi-Agent Example

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

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

Python SDK

LangGraph

Google ADK

aion.yaml Configuration

Complete Example

Root Structure

Configuration Settings

Required Field

Common Optional Fields

Path Patterns

Skills

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

​Configuration Settings

​Required Field

​Common Optional Fields

​Path Patterns

​Skills

​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

Configuration Settings

Required Field

Common Optional Fields

Path Patterns

Skills

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