Skip to main content

​
Complete Example

This example shows a fully formed aion.yaml with multiple agents, capabilities, 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"]
      capabilities:
        streaming: true
        pushNotifications: false
      skills:
        - id: "ticket_search"
          name: "Ticket Search"
          description: "Search historical support tickets"
          tags: ["support", "search"]
          examples:
            - "Find similar tickets for login issues"
      configuration:
        model:
          type: "string"
          default: "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

SettingRequiredDescription
aion.agentsyesMap of agent IDs to agent configuration blocks.
aion.agents.<agent_id>.pathyesImport target (module_or_file[:symbol]) for agent discovery.
aion.agents.<agent_id>.frameworknoFramework adapter selection (langgraph or adk).
aion.agents.<agent_id>.capabilitiesnoDeclares runtime capabilities such as streaming and push notifications.
aion.agents.<agent_id>.skillsnoSkill metadata surfaced in agent card output.
aion.agents.<agent_id>.configurationnoTyped configuration schema exposed via configuration metadata.
aion.http.<mount_path>noOptional dynamic ASGI/FastAPI app mounts on the agent server.

​
Required Field

FieldTypeDescription
pathstringImport path to the agent object or factory function.

​
Common Optional Fields

FieldTypeDefaultNotes
frameworklanggraph or adklanggraphRuntime adapter target.
namestringAgentAgent display name in card metadata.
descriptionstringemptyHuman-readable summary.
versionsemver string1.0.0Format X.Y.Z.
input_modesstring[]["text"]Allowed: text, audio, image, video, json.
output_modesstring[]["text"]Allowed: text, audio, image, video, json.

​
Path Patterns

path accepts module_or_file[:symbol].
PatternExampleBehavior
File path + symbol./agent.py:build_graphLoads a file module, then resolves the named symbol.
File path auto-discovery./agent.pyLoads a file module, then auto-discovers a supported object.
Dotted module + symbolmy_project.agent:create_agentImports module from PYTHONPATH, then resolves symbol.
Dotted module auto-discoverymy_project.agentImports 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.

​
Capabilities

capabilities:
  streaming: true
  pushNotifications: false

​
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
  • integer
  • float
  • boolean
  • array
  • object

​
Common Field Properties

These properties are available on all agent-configuration field types.
PropertyTypeRequiredDescription
typestringyesField type (string, integer, float, boolean, array, object).
descriptionstringnoHuman-readable field description.
defaultanynoDefault value when not provided.
requiredbooleannoWhether the field must be provided.
nullablebooleannoWhether null is allowed.
enumarraynoRestricts values to a fixed set.

​
String Fields

PropertyTypeDescription
min_lengthintegerMinimum character length.
max_lengthintegerMaximum character length.
enumstring[]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"]

​
Integer Fields

PropertyTypeDescription
minintegerInclusive minimum value.
maxintegerInclusive maximum value.
enuminteger[]Allowed integer values list.
Example: 
configuration:
  max_retries:
    type: "integer"
    default: 3
    min: 0
    max: 10

​
Float Fields

PropertyTypeDescription
minnumberInclusive minimum value.
maxnumberInclusive maximum value.
enumnumber[]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

PropertyTypeDescription
min_lengthintegerMinimum array item count.
max_lengthintegerMaximum array item count.
itemsobjectSchema 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

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