Skip to main content

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

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

​
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
  • 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.
PropertyTypeRequiredDescription
typestringyesField type (string, llm, integer, float, boolean, array, object).
descriptionstringnoHuman-readable field description.
defaultanynoDefault value when supported by the field type and no value is provided.
requiredbooleannoWhether the field must be provided.
nullablebooleannoWhether null is allowed.

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

​
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

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"