> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# aion.yaml Configuration

> Reference for agent configuration in aion.yaml.

## Complete Example

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

```yaml theme={null}
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"]
        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

```yaml theme={null}
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

```yaml theme={null}
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.

```yaml theme={null}
configuration:
  temperature:
    type: "float"
    default: 0.7
    min: 0.0
    max: 2.0
```

Supported field types:

* `string`
* `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`, `llm`, `integer`, `float`, `boolean`, `array`, `object`). |
| `description` | string  | no       | Human-readable field description.                                               |
| `default`     | any     | no       | Default value when supported by the field type and no value is provided.        |
| `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:

```yaml theme={null}
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"]
```

### 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
configuration:
  temperature:
    type: "float"
    default: 0.7
    min: 0.0
    max: 2.0
```

### Boolean Fields

Boolean fields use common properties only.

Example:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
aion:
  agents:
    support:
      path: "./support.py:build_graph"
      framework: "langgraph"

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