Skip to content

configure-an-agent.md

Latest commit

 

History

History
177 lines (134 loc) · 4.69 KB

configure-an-agent.md

File metadata and controls

177 lines (134 loc) · 4.69 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 (Claude, Ark)

One agent can orchestrate others in coordinator mode:

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

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.