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

# Agent Development

> Create AI agents using dotprompt format

## What Are Station Agents?

Station agents are AI-powered automation tools that:

* Execute multi-step tasks autonomously
* Access tools and APIs through MCP servers
* Run on your infrastructure with your credentials

<Note>
  Unlike ChatGPT or Claude, Station agents have direct access to your tools (AWS, databases, filesystems) and can execute complex workflows without copy-pasting commands.
</Note>

## Dotprompt Format

Every agent is a `.prompt` file with YAML frontmatter and a template body:

```yaml theme={null}
---
metadata:
  name: "Cost Analyzer"
  description: "Analyzes AWS costs and finds savings"
  tags: ["finops", "aws"]
model: gpt-4o-mini
max_steps: 8
tools:
  - "__get_cost_and_usage"
  - "__list_cost_allocation_tags"
---

{{role "system"}}
You are a FinOps analyst specializing in AWS cost analysis.

Your process:
1. Query AWS Cost Explorer for the past 30 days
2. Identify cost spikes exceeding 20% baseline
3. Break down costs by service
4. Provide actionable recommendations

{{role "user"}}
{{userInput}}
```

## Frontmatter Reference

| Field                  | Type    | Required | Description                       |
| ---------------------- | ------- | -------- | --------------------------------- |
| `metadata.name`        | string  | Yes      | Agent display name                |
| `metadata.description` | string  | Yes      | What the agent does               |
| `metadata.tags`        | array   | No       | Categories for search             |
| `model`                | string  | Yes      | AI model to use                   |
| `max_steps`            | integer | Yes      | Maximum tool calls (5-15 typical) |
| `tools`                | array   | Yes      | MCP tools the agent can use       |

## Model Selection

| Model                      | Use Case                | Speed  | Cost   |
| -------------------------- | ----------------------- | ------ | ------ |
| `gpt-4o-mini`              | Simple tasks, file ops  | Fast   | Low    |
| `gpt-4o`                   | Complex reasoning       | Medium | Medium |
| `claude-3-5-sonnet-latest` | Code analysis, security | Medium | Medium |

## Creating Agents

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Interactive creation
    stn agent create

    # With flags
    stn agent create --name "my-agent" --model gpt-4o-mini
    ```
  </Tab>

  <Tab title="File">
    Create a `.prompt` file in your environment's agents directory:

    ```
    ~/.config/station/environments/default/agents/my-agent.prompt
    ```
  </Tab>
</Tabs>

## Running Agents

```bash theme={null}
# Run an agent
stn agent run "Cost Analyzer" "Analyze last month's AWS spending"

# With real-time output
stn agent run "Cost Analyzer" "Find cost savings" --tail
```

## Discovering Tools

List available MCP tools for your agents:

```bash theme={null}
# All tools in current environment
stn mcp tools

# Search for specific tools
stn mcp tools | grep aws
```

## Coding Backends

Agents can be enhanced with coding capabilities that allow them to read, write, and modify files.

### OpenCode Backend

Enable AI coding with filesystem access via OpenCode:

```yaml theme={null}
---
metadata:
  name: "Code Assistant"
  description: "AI coding assistant"
model: openai/gpt-4o
coding:
  enabled: true
---

You are an expert software engineer. Use coding tools to implement features.
```

This gives the agent these tools:

| Tool            | Description                                |
| --------------- | ------------------------------------------ |
| `coding_open`   | Start a coding session in a directory      |
| `code`          | Execute coding tasks (read/write/refactor) |
| `coding_close`  | End the session                            |
| `coding_commit` | Commit changes to git                      |
| `coding_push`   | Push to remote repository                  |

<Note>
  The transport mechanism (HTTP or NATS) is configured at the Station level, not per-agent. This makes agent definitions portable across different deployments. See [OpenCode Backend](/station/opencode) for backend configuration.
</Note>

### Coding Frontmatter Options

| Field                   | Type    | Required | Description                        |
| ----------------------- | ------- | -------- | ---------------------------------- |
| `coding.enabled`        | boolean | Yes      | Enable coding tools for this agent |
| `coding.workspace_path` | string  | No       | Default workspace directory        |

<Card title="OpenCode Backend" icon="code" href="/station/opencode">
  Full guide to OpenCode integration, HTTP vs NATS backends, and container mode
</Card>

### Sandbox Backend

For isolated code execution in containers (different from OpenCode), use the sandbox backend:

```yaml theme={null}
---
model: openai/gpt-4o
sandbox:
  mode: code
  session: workflow
---
```

<Card title="Sandbox Execution" icon="box" href="/station/sandbox">
  Run code safely in isolated Docker containers
</Card>

## Notifications

Enable agents to send webhook notifications (ntfy, Slack, or any webhook endpoint):

```yaml theme={null}
---
model: anthropic/claude-sonnet-4-20250514
notify: true
---
You are a monitoring agent. Send notifications when tasks complete or issues arise.
```

This gives the agent the `notify` tool with parameters:

| Parameter  | Description                                       |
| ---------- | ------------------------------------------------- |
| `message`  | Notification content (required)                   |
| `title`    | Subject line (optional)                           |
| `priority` | `min`, `low`, `default`, `high`, `urgent`         |
| `tags`     | Emoji tags like `["warning", "white_check_mark"]` |

<Card title="Notifications" icon="bell" href="/station/notifications">
  Full guide to webhook configuration and formats
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Notifications" icon="bell" href="/station/notifications">
    Send webhook notifications from agents
  </Card>

  <Card title="MCP Tools" icon="plug" href="/station/mcp-tools">
    Connect agents to external services
  </Card>

  <Card title="Multi-Agent Teams" icon="users" href="/station/multi-agent-teams">
    Build hierarchical agent teams
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/station/workflows">
    Orchestrate multi-step agent tasks
  </Card>

  <Card title="Evaluation" icon="chart-line" href="/station/evaluation">
    Test and score your agents
  </Card>
</CardGroup>