# Configuration Reference

The `manifest.yaml` file is the heart of every `.agent` package. It tells
runtimes how to start your agent and tells registries how to list it.

The manifest has two zones:

- **Zone 1 (open core)** — authored by the developer. Contains identity,
  runtime, capabilities, execution, and resource configuration.
- **Zone 2 (`_package`)** — auto-generated by `agent pack`. Contains
  hashes, timestamps, and package metadata. Never edit this by hand.

## Identity

Required fields that identify your agent.

```yaml
spec_version: "1.0"
name: my-agent
version: "0.1.0"
description: "One-line summary of what this agent does."
```

| Field | Required | Description |
|-------|----------|-------------|
| `spec_version` | yes | Manifest spec version. Currently `"1.0"`. |
| `name` | yes | Lowercase with hyphens and digits only. Must start with a letter. Pattern: `^[a-z][a-z0-9-]*$` |
| `version` | yes | Semantic version (`MAJOR.MINOR.PATCH`). Pre-release and build metadata allowed per SemVer 2.0. |
| `description` | yes | Short summary shown in registries and inspect output. |
| `display_name` | no | Human-friendly name (e.g. `"Fraud Detection Agent"`). |
| `author` | no | Author name or handle. |
| `organization` | no | Organization name. |
| `license` | no | SPDX license identifier (e.g. `"MIT"`, `"Apache-2.0"`). |
| `tags` | no | List of searchable tags. |

### Naming rules

| Valid | Invalid |
|-------|---------|
| `fraud-detection` | `Fraud_Detection` |
| `my-agent-2` | `my agent` |
| `data-pipeline` | `data.pipeline` |

## Runtime

Declares the language, entry point, and dependencies.

```yaml
runtime:
  language: python
  language_version: "3.11"
  entry_point: src/agent.py
  entry_function: main
  dependencies: requirements.txt
```

| Field | Required | Description |
|-------|----------|-------------|
| `language` | yes | One of: `python`, `nodejs`, `typescript`, `go`, `rust` |
| `language_version` | yes | Minimum required version string. |
| `entry_point` | yes | Relative path to the file containing the agent entry function. |
| `entry_function` | no | Function name to call. Default: `main`. |
| `dependencies` | no | Relative path to the dependency file (e.g. `requirements.txt`, `package.json`). |

## Model (optional)

LLM preferences for the agent.

```yaml
model:
  agnostic: true
  preferred: "claude-sonnet-4-20250514"
  minimum_context: 16000
  alternatives:
    - "gpt-4o"
```

| Field | Required | Description |
|-------|----------|-------------|
| `agnostic` | no | `true` if the agent works with any LLM. Default: `false`. |
| `preferred` | no | Preferred model identifier. |
| `minimum_context` | no | Minimum context window size in tokens. |
| `alternatives` | no | List of acceptable alternative model identifiers. |

## Framework (optional)

Declares which agent framework the code uses.

```yaml
framework:
  name: langchain
  version: "0.1"
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | One of: `langchain`, `crewai`, `autogen`, `llamaindex`, `haystack`, `semantic-kernel`, `dspy`, `smolagents`, `pydantic-ai`, `custom` |
| `version` | no | Framework version string. |

## Capabilities

Lists every tool the agent exposes.

```yaml
capabilities:
  tools:
    - id: scan_transaction
      description: "Read transaction data from the incoming event stream."
      scope: read
      required: true
      targets:
        - "transactions.*"
    - id: flag_transaction
      description: "Mark a transaction as suspicious."
      scope: write
      required: true
      targets:
        - "cases.flags"
```

### Tool fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | yes | Unique tool identifier. |
| `description` | yes | What the tool does. |
| `scope` | yes | Access scope: `read`, `write`, `execute`, `delete`, or `admin` |
| `required` | yes | `true` if the runtime must provide this tool. |
| `targets` | no | Resource patterns the tool operates on (e.g. `"transactions.*"`). |
| `constraints` | no | Dict of tool-specific limits. |

## Permissions (optional)

Data classification and environment variable access rules.

```yaml
permissions:
  data_classes:
    - name: pii
      access: read
  environments:
    allowed:
      - API_KEY
      - DATABASE_URL
    denied:
      - SECRET_TOKEN
```

| Section | Field | Description |
|---------|-------|-------------|
| `data_classes[]` | `name` | Classification name (e.g. `pii`, `phi`). |
| `data_classes[]` | `access` | Access level string. |
| `environments` | `allowed` | List of environment variable names the agent may read. |
| `environments` | `denied` | List of environment variable names the agent must not read. |

## Execution

How and when the agent runs.

```yaml
execution:
  type: triggered
  triggers:
    - event: transaction.created
  timeout_minutes: 30
```

| Field | Required | Description |
|-------|----------|-------------|
| `type` | yes | One of: `scheduled`, `triggered`, `continuous`, `on-demand` |
| `schedule` | no | Cron expression (for `scheduled` type). |
| `timezone` | no | IANA timezone string. Default: `"UTC"`. |
| `triggers` | no | List of trigger definitions (for `triggered` type). Each item has an `event` key. |
| `poll_interval_seconds` | no | Polling interval for `continuous` agents. |
| `permitted_windows` | no | Time windows when execution is allowed (see below). |
| `max_concurrent_instances` | no | Maximum parallel instances. Default: `1`. |
| `timeout_minutes` | no | Maximum run time in minutes. |
| `retry` | no | Retry configuration (see below). |

### Execution types

| Type | Trigger | Example |
|------|---------|---------|
| `scheduled` | Cron schedule | Run every 6 hours |
| `triggered` | External event | Run when a transaction is created |
| `continuous` | Long-running | Poll a queue every 30 seconds |
| `on-demand` | Manual invocation | User runs `agent run` |

### Permitted windows

```yaml
execution:
  type: scheduled
  schedule: "0 */6 * * *"
  permitted_windows:
    - days: ["mon", "tue", "wed", "thu", "fri"]
      hours: "09:00-17:00"
      timezone: "America/New_York"
```

### Retry configuration

```yaml
execution:
  type: triggered
  triggers:
    - event: order.placed
  retry:
    max_attempts: 3
    backoff_seconds: 60
```

| Field | Default | Description |
|-------|---------|-------------|
| `max_attempts` | `3` | Maximum number of retry attempts. |
| `backoff_seconds` | `60` | Seconds between retries. |

## Resources (optional)

Compute resource requests for the runtime.

```yaml
resources:
  memory_mb: 512
  cpu_shares: 256
  network: outbound-only
```

| Field | Required | Description |
|-------|----------|-------------|
| `memory_mb` | no | Requested memory in megabytes. |
| `cpu_shares` | no | Relative CPU weight. |
| `network` | no | Network access: `none`, `inbound`, `outbound-only`, or `bidirectional` |

## Zone 2 — `_package`

Auto-generated by `agent pack`. Do not edit.

```yaml
_package:
  format: agent-package-format
  format_version: "1.0"
  packaged_at: "2025-01-15T12:00:00+00:00"
  packaged_by: "agentpk/0.1.0"
  manifest_hash: "sha256:abc123..."
  files_hash: "sha256:def456..."
  total_files: 5
  package_size_bytes: 2048
```

When `--analyze` is used during packing, the `_package` block also
includes an `analysis` sub-block with the trust score and analysis
metadata. See [agent_analyzer.md](agent_analyzer.md) for details.

| Field | Description |
|-------|-------------|
| `format` | Always `"agent-package-format"`. |
| `format_version` | Package format version. |
| `packaged_at` | ISO 8601 build timestamp (UTC). |
| `packaged_by` | Tool and version that created the package. |
| `manifest_hash` | SHA-256 hash of Zone 1 content. |
| `files_hash` | Combined SHA-256 of all user files. |
| `total_files` | Number of files in the archive. |
| `package_size_bytes` | Archive size in bytes. |

## Complete example

```yaml
spec_version: "1.0"
name: fraud-detection
display_name: "Fraud Detection Agent"
version: "0.1.0"
description: "Scans financial transactions in real time and flags anomalies."
author: "agentpk contributors"
license: "MIT"
tags:
  - fraud
  - compliance
  - finance

runtime:
  language: python
  language_version: "3.11"
  entry_point: src/agent.py
  entry_function: main
  dependencies: requirements.txt

capabilities:
  tools:
    - id: scan_transaction
      description: "Read transaction data from the incoming event stream."
      scope: read
      required: true
      targets:
        - "transactions.*"
    - id: flag_transaction
      description: "Mark a transaction as suspicious and write the flag to the case database."
      scope: write
      required: true
      targets:
        - "cases.flags"
    - id: alert_compliance_team
      description: "Send a notification to the compliance team channel."
      scope: write
      required: false
      targets:
        - "notifications.compliance"

execution:
  type: triggered
  triggers:
    - event: transaction.created
  timeout_minutes: 30

resources:
  memory_mb: 512
  cpu_shares: 256
  network: outbound-only
```

## See also

- [Quickstart](quickstart.md) — get up and running
- [CLI Reference](cli.md) — every command and flag
- [Specification](../SPEC.md) — the formal `.agent` format spec
