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

# Agent Workflow

> How agents propose changes and humans approve them

Runtime lets AI agents propose infrastructure changes while keeping humans in the loop. Agents can request features, secrets, and permissions - humans review and approve.

## How it works

```mermaid theme={null}
flowchart TB
    Agent[AI Agent] --> Propose[requests.yaml] --> Human[Human Review] --> Approve[runtm approve]
    
    style Agent fill:#f4f4f5,stroke:#18181b,stroke-width:1px,color:#18181b
    style Propose fill:#f4f4f5,stroke:#18181b,stroke-width:1px,color:#18181b
    style Human fill:#f4f4f5,stroke:#18181b,stroke-width:1px,color:#18181b
    style Approve fill:#18181b,stroke:#18181b,stroke-width:2px,color:#fafafa
```

1. AI agent creates `runtm.requests.yaml` with proposed changes
2. Human reviews the proposed changes
3. Human runs `runtm approve` to merge changes into `runtm.yaml`
4. Human deploys

## The requests file

AI agents propose changes by creating `runtm.requests.yaml`:

```yaml theme={null}
requested:
  features:
    database: true
    reason: "Need persistent storage for user data"
  
  env_vars:
    - name: STRIPE_API_KEY
      secret: true
      required: true
      reason: "Payment processing"

notes:
  - "Adding Stripe integration for payments"
```

## Reviewing changes

Preview what would change:

```bash theme={null}
runtm approve --dry-run
```

## Applying changes

If everything looks good:

```bash theme={null}
runtm approve
```

This merges the requested changes into `runtm.yaml` and deletes the requests file.

To reject, simply delete the file:

```bash theme={null}
rm runtm.requests.yaml
```

## What agents can request

### Features

```yaml theme={null}
requested:
  features:
    database: true
    auth: true       # web-app only
    reason: "Why this is needed"
```

### Environment variables

```yaml theme={null}
requested:
  env_vars:
    - name: API_KEY
      type: string
      secret: true
      required: true
      reason: "External API authentication"
```

### Egress allowlist

```yaml theme={null}
requested:
  egress_allowlist:
    - "api.stripe.com"
    - "api.openai.com"
```

## For agent developers

If you're building an AI agent that integrates with Runtime:

```python theme={null}
import yaml

request = {
    "requested": {
        "features": {
            "database": True,
            "reason": "Need persistent storage"
        },
        "env_vars": [
            {
                "name": "OPENAI_API_KEY",
                "secret": True,
                "required": True,
                "reason": "LLM API calls"
            }
        ]
    },
    "notes": ["Adding AI features"]
}

with open("runtm.requests.yaml", "w") as f:
    yaml.dump(request, f)
```

> [!TIP]
>
> Always include a `reason` field explaining why each change is needed. It helps humans make informed decisions.

> [!NOTE]
>
> In v1, `runtm approve` is informational only - deployments work without approval. Future versions will enforce policy compliance for organizations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.