> ## 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 Manifest

> Full reference for agent.yaml — the OpenGAP agent manifest format.

`agent.yaml` is the single required file in an OpenGAP agent. It declares the agent's identity, model, configuration, and feature flags. Every OpenGAP-compliant runtime reads `agent.yaml` to understand how to execute the agent.

## Full schema

```yaml theme={null}
# ─── Required ───────────────────────────────────────────────────────────────
opengap: "0.4"              # OpenGAP spec version this agent targets
name: my-agent              # unique identifier (kebab-case recommended)
version: "1.0.0"            # agent version (semver)

# ─── Metadata (optional) ────────────────────────────────────────────────────
description: "What this agent does"
author: "Your Name <you@example.com>"
homepage: "https://github.com/your-org/my-agent"
tags: [research, writing]
license: MIT

# ─── Model ──────────────────────────────────────────────────────────────────
model:
  provider: openai           # openai | anthropic | azure-openai | ollama | lyzr
  name: gpt-4o               # model identifier
  temperature: 0.0           # 0.0–2.0 (default: 0.0)
  max_tokens: 4096           # max output tokens
  timeout: 60                # per-call timeout in seconds
  # Provider-specific fields:
  api_key: ${OPENAI_API_KEY} # env var reference
  base_url: ~                # override API base URL (for proxies)

# ─── System prompt ──────────────────────────────────────────────────────────
system_prompt: |
  You are a helpful assistant...

# Or reference an external file:
# system_prompt_file: prompts/system.txt

# ─── Skills ─────────────────────────────────────────────────────────────────
skills:
  path: skills/              # directory or list of directories
  include: ["*.py"]          # glob patterns (default: all .py files)
  exclude: ["*_test.py", "__pycache__"]

# ─── Hooks ──────────────────────────────────────────────────────────────────
hooks:
  path: hooks/

# ─── Flows ──────────────────────────────────────────────────────────────────
flows:
  path: flows/

# ─── Memory ─────────────────────────────────────────────────────────────────
memory:
  enabled: false             # default: false
  provider: local            # local | lyzr | custom
  max_history: 20            # conversation turns to inject into context
  path: ~/.gitagent/memory   # for local provider

# ─── Built-in tools ─────────────────────────────────────────────────────────
tools:
  web_search:
    enabled: false
    provider: serper         # serper | serpapi | brave | duckduckgo
    api_key: ${SERPER_API_KEY}
    num_results: 5
  file_ops:
    enabled: false
    allowed_paths: []
  http:
    enabled: false
    allowed_domains: []
    block_private_ips: true
  code_exec:
    enabled: false           # off by default — security risk
    timeout: 10
    memory_mb: 128

# ─── Execution ──────────────────────────────────────────────────────────────
execution:
  max_iterations: 20         # max agent loop iterations before stopping
  timeout: 300               # total run timeout in seconds
  parallel_skills: false     # allow multiple skill calls per LLM step

# ─── Telemetry ──────────────────────────────────────────────────────────────
telemetry:
  enabled: false
  provider: langship          # langship | otlp | stdout
  endpoint: ${LANGSHIP_ENDPOINT}
  api_key: ${LANGSHIP_API_KEY}
  project: my-agent
  sample_rate: 1.0

# ─── Audit ──────────────────────────────────────────────────────────────────
audit:
  enabled: false
  path: ./logs/audit.jsonl

# ─── Plugins ────────────────────────────────────────────────────────────────
plugins: []
```

## Environment variable interpolation

Any scalar value can reference an environment variable:

```yaml theme={null}
model:
  api_key: ${OPENAI_API_KEY}               # required — fails if not set
  name: ${AGENT_MODEL:-gpt-4o}            # with default value
  temperature: ${AGENT_TEMP:-0.0}         # numeric default
```

Syntax: `${VAR_NAME}` or `${VAR_NAME:-default}`.

## Required fields

| Field            | Type   | Description                  |
| ---------------- | ------ | ---------------------------- |
| `opengap`        | string | Spec version (e.g., `"0.4"`) |
| `name`           | string | Agent identifier             |
| `version`        | string | Semver version string        |
| `model.provider` | string | Model provider               |
| `model.name`     | string | Model identifier             |

All other fields are optional.

## Model providers

| Provider       | `name` examples                                         |
| -------------- | ------------------------------------------------------- |
| `openai`       | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`                  |
| `anthropic`    | `claude-3-5-sonnet-20241022`, `claude-3-haiku-20240307` |
| `azure-openai` | Your deployment name                                    |
| `ollama`       | `llama3.2`, `mistral`, `codellama`                      |
| `lyzr`         | Any Lyzr-hosted model                                   |

## Validation

Validate your `agent.yaml` against the schema:

```bash theme={null}
gitagent validate
# or
gitagent validate --file path/to/agent.yaml
```

The validator checks:

* All required fields are present
* Field types match the schema
* Environment variable references use valid syntax
* File paths referenced (skills, hooks, flows) exist on disk
* The `opengap` version is supported by the installed runtime