> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# agent.yaml Reference

> The central manifest for an OpenGAP agent: model, tools, skills, compliance, MCP servers, and A2A protocol.

`agent.yaml` is the central manifest for an OpenGAP agent. Three files define your agent: `agent.yaml` is one of them, and the only one required alongside `SOUL.md`.

## Minimal Configuration

```yaml theme={null}
spec_version: "0.4.0"
name: code-review-agent
version: 1.0.0
description: Automated code review agent
author: gitagent-examples
license: MIT
model:
  preferred: claude-sonnet-4-5-20250929
  fallback:
    - claude-haiku-4-5-20251001
  constraints:
    temperature: 0.2
    max_tokens: 4096
skills:
  - code-review
tools:
  - lint-check
  - complexity-analysis
runtime:
  max_turns: 20
  timeout: 120
```

## Full Configuration (v0.4 fields)

```yaml theme={null}
spec_version: "0.4.0"
name: my-agent
version: 1.0.0
description: A full-featured agent example

model:
  preferred: "claude-sonnet-4-6"
  fallback: ["claude-haiku-4-5-20251001"]
  constraints:
    temperature: 0.7
    max_tokens: 4096

tools: [cli, read, write, memory]
skills:
  - code-review

runtime:
  max_turns: 50
  timeout: 300

# Agent inheritance — clone identity + rules from a parent repo
extends: https://github.com/user/parent-agent.git

# Git-based skill/tool dependencies (opengap install resolves these)
dependencies:
  - name: shared-skills
    source: https://github.com/team/shared-skills
    version: main
    mount: deps/shared

# Sub-agent definitions
agents:
  researcher:
    description: "Research assistant"
    delegation:
      mode: auto

delegation:
  mode: auto

# MCP server configuration (v0.4)
mcp_servers:
  my-server:
    command: "npx"
    args: ["-y", "@my/mcp-server"]

# Agent-to-Agent (A2A) protocol support (v0.4)
a2a:
  url: "https://my-agent.example.com/a2a"
  capabilities: ["task", "stream"]
  authentication:
    type: bearer
  protocols: ["a2a/1.0"]

compliance:
  risk_tier: high
  supervision:
    human_in_the_loop: "always"
  frameworks: [finra, federal_reserve]
  recordkeeping:
    audit_logging: true
    retention_period: "7y"
  financial_governance:
    spending:
      max_per_transaction_cents: 10000
    approval:
      require_above_cents: 5000
    firewall: "valkurai"
```

## Key Fields

### model

| Field                     | Description                     |
| ------------------------- | ------------------------------- |
| `preferred`               | Primary model identifier        |
| `fallback`                | Ordered list of fallback models |
| `constraints.temperature` | Default sampling temperature    |
| `constraints.max_tokens`  | Max tokens per LLM call         |

### extends

URL to a parent agent git repo. `opengap install` clones the parent into `.gitagent/parent/`. Merge behavior when running with the `claude` adapter:

| File                | Behavior                                                               |
| ------------------- | ---------------------------------------------------------------------- |
| `SOUL.md`           | Child replaces parent entirely; falls back to parent if child has none |
| `RULES.md`          | Union: parent first, then child appended                               |
| `skills/`, `tools/` | Union: child shadows parent on name collision                          |

<Warning>
  This merge behavior is only implemented in the `claude` adapter. Other adapters (OpenAI, CrewAI, etc.) do not read from `.gitagent/parent/`: `extends` has no effect when exporting to those formats.
</Warning>

### mcp\_servers (v0.4)

MCP server configuration. Each entry specifies a command and args to spawn an MCP-compatible server the agent can use as a tool provider.

### a2a (v0.4)

Agent-to-Agent protocol support. Exposes the agent as an A2A endpoint so other agents can call it directly using the A2A/1.0 protocol.

### compliance

See the [Compliance](/open-source/opengap/compliance) page for the full reference: risk tiers, HITL, audit logging, financial governance, and regulatory frameworks.

<CardGroup cols={2}>
  <Card title="Compliance" icon="shield-check" href="/open-source/opengap/compliance">
    Full compliance schema and regulatory framework reference
  </Card>

  <Card title="Skills" icon="sparkles" href="/open-source/opengap/skills/overview">
    Skill definitions referenced in agent.yaml
  </Card>

  <Card title="Adapters" icon="plug" href="/open-source/opengap/adapters">
    Export agent.yaml to any framework
  </Card>

  <Card title="CLI" icon="terminal" href="/open-source/opengap/cli">
    opengap validate, run, and export commands
  </Card>
</CardGroup>