Skip to content

agent-config-reference.md

Latest commit

 

History

History
93 lines (69 loc) · 2.85 KB

agent-config-reference.md

File metadata and controls

93 lines (69 loc) · 2.85 KB

AgentConfig File Reference

AgentConfig.from_file() loads .yaml, .yml, and .json files into the AgentConfig dataclass in packages/agent-os/src/agent_os/base_agent.py.

Use ../examples/agent_config.yaml as the baseline example when creating new agent configs.

Supported file keys

Field Type Required Default Notes
agent_id string Yes, in practice "agent" when omitted Must match ^[a-zA-Z0-9][a-zA-Z0-9-]{2,63}$. Set this explicitly to avoid collisions between agents.
agentId string No None Camel-case alias accepted only when agent_id is absent. Prefer agent_id in new configs.
policies array of strings No [] Policy names copied into every execution context created by the agent.
metadata mapping No {} Free-form metadata copied into the execution context before each request.
max_audit_log_size integer No 10000 Maximum number of in-memory audit entries retained by BaseAgent.
max_metadata_size_bytes integer No 1048576 Per-value byte limit checked when metadata is copied into a new execution context.

Constructor-only fields

The AgentConfig dataclass also accepts state_backend when instantiated in Python, but from_file() does not read a state_backend key from YAML or JSON files. Configure custom state backends in code:

from agent_os.base_agent import AgentConfig
from agent_os.state_backends import InMemoryStateBackend

config = AgentConfig(
    agent_id="agent-with-custom-state",
    state_backend=InMemoryStateBackend(),
)

Validation rules

agent_id

  • Minimum length: 3 characters
  • Maximum length: 64 characters
  • First character: letter or number
  • Remaining characters: letters, numbers, or -

Examples:

  • Valid: research-agent-01
  • Invalid: my_agent because _ is not allowed
  • Invalid: ab because it is too short

metadata

Metadata is accepted as free-form YAML/JSON, but each value is size-checked later when BaseAgent creates a new execution context. If any single value exceeds max_metadata_size_bytes, Agent OS raises a ValueError.

Valid example

agent_id: review-agent-01
policies:
  - read_only
  - no_pii
metadata:
  environment: staging
  owner: team-platform
max_audit_log_size: 5000
max_metadata_size_bytes: 262144

Invalid examples

Invalid agent_id

agent_id: my_agent
policies:
  - read_only

This fails validation because agent_id contains _.

Metadata value too large at runtime

agent_id: oversized-metadata-demo
metadata:
  huge_blob: "<very large string or object here>"
max_metadata_size_bytes: 1024

This file can load successfully, but BaseAgent raises a ValueError when it builds an execution context if huge_blob is larger than 1024 bytes.