Skip to content

configure-an-agent.md

Latest commit

 

History

History
185 lines (139 loc) · 5.75 KB

configure-an-agent.md

File metadata and controls

185 lines (139 loc) · 5.75 KB
Raw

Configure an agent

This guide builds an agents.yaml up from the minimal case to a full stack. Runnable versions of each stage live under examples/. For every field, see the Configuration reference.

Minimal config

The smallest useful config declares one provider and one agent:

version: "1"

providers:
  claude:
    api_key: ${ANTHROPIC_API_KEY}

defaults:
  provider: claude

agents:
  assistant:
    description: "General-purpose coding assistant"
    model: claude-sonnet-4-6
    instructions: |
      You are a coding assistant.
    tools:
      builtin: [read, glob, grep]
  • version — config schema version (currently "1").
  • providers — one block per provider you target; each holds its credentials.
  • defaults.provider — which provider plan/apply use when --provider is omitted. Set it to all to target every declared provider at once.
  • agents — a map of agent name → definition.

Secrets use ${VAR_NAME} and resolve from .env. Never inline a real key.

Environments

An environment is the cloud runtime an agent runs in — its network policy and preinstalled packages.

environments:
  dev:
    description: "Development environment with full network access"
    config:
      type: cloud
      networking:
        type: unrestricted

  staging:
    config:
      type: cloud
      networking:
        type: limited
        allow_mcp_servers: true
        allow_package_managers: true
        allowed_hosts:
          - "api.github.com"
          - "registry.npmjs.org"
      packages:
        apt: [git, curl]
        npm: [typescript]
      setup_script: |
        set -euo pipefail
        install -d /data/workspace/.openagentpack
        test -f /data/workspace/.openagentpack/ready || date -u > /data/workspace/.openagentpack/ready

Reference an environment from an agent with environment: dev.

Qoder supports config.setup_script for both cloud and self-hosted environments. It runs the script with /bin/bash -lc after declared packages are installed. The UTF-8 limit is 64 KB and the timeout is 10 minutes; a non-zero exit prevents the Session from starting. The script runs once per sandbox and runs again when that sandbox is rebuilt, so make it idempotent. Do not embed credentials—use vaults or environment-backed secret references. Other providers currently reject setup_script rather than silently ignoring it.

Instructions

instructions accepts either an inline string or a path to a file:

agents:
  lead:
    instructions: ./prompts/lead.md    # loaded relative to the config file

Tools

tools:
  builtin: [read, glob, grep, web_search, web_fetch, write, edit, bash]
  permissions:
    read: allow
    glob: allow
    bash: ask

Built-in tool names are lowercase in config. When targeting Qoder (which uses PascalCase natively), OpenAgentPack converts them automatically — see Provider reference.

Skills

A skill is a reusable capability module uploaded from a local directory:

skills:
  code-review:
    source: ./skills/code-review/
    description: "Structured code review with severity levels"

agents:
  reviewer:
    skills: [code-review]

See Use skills.

Vaults and MCP servers

A vault stores credentials for external tool servers reached over MCP:

vaults:
  api-credentials:
    display_name: "API Credentials"
    credentials:
      - name: github-mcp
        mcp_server_url: "https://mcp.example.com/github"
        type: static_bearer
        access_token: ${MCP_GITHUB_TOKEN}
        protocol: streamable_http

agents:
  lead:
    mcp_servers:
      - name: github
        url: "https://mcp.example.com/github"
    vault: api-credentials

See Use MCP and vaults.

Memory stores (Qoder, Claude beta, Ark)

memory_stores:
  project-memory:
    description: "Persistent project context"

agents:
  assistant:
    memory_stores: [project-memory]

Multi-agent coordination

One agent can orchestrate others in coordinator mode. All four providers support it:

agents:
  lead:
    multiagent:
      type: coordinator
      agents: [researcher, reviewer]

Rules:

  • multiagent.agents accepts project logical names and explicit external Managed Agent references such as { agent_id: agent_external_1 }. External references are not lifecycle-managed by OpenAgentPack and are not supported by Qoder Forward delivery.
  • Logical-name members must be declared in the same config; a coordinator cannot orchestrate itself, nest another coordinator, or form a cycle (direct or indirect). External { agent_id } members are treated as non-owned leaves. Rosters are capped at 20 members.
  • On Qoder, every member must use the same delivery type as its coordinator — all Managed Agents (id references) or all Forward Templates (template_id references).

Examples: examples/claude/multiagent/ · examples/qoder/multiagent/ · examples/qoder/multiagent-forward/ · examples/bailian/multiagent/ · examples/ark/multiagent/.

Deployments

A deployment bundles an agent, its runtime bindings, initial events, and a schedule into a repeatable run unit managed by plan/apply:

deployments:
  nightly-review:
    agent: reviewer
    environment: dev
    schedule: "0 2 * * *"

See Manage deployments.

Full example

See examples/claude/full/ for a config that combines environments, vaults, skills, multi-agent coordination, and metadata in one file.