# {{ agent_name }} - {% if sdk_type == "codex_agent_sdk" %}Codex SDK{% else %}Claude Agent SDK{% endif %} Template

{% if sdk_type == "codex_agent_sdk" %}
This template creates an agent powered by OpenAI Agents `codex_tool`. It supports
multi-turn conversations by persisting the Codex thread ID in task state.
{% else %}
This template creates an intelligent agent powered by the Claude Agent SDK. Your agent can have multi-turn conversations, read/write files, run commands, and maintain context across interactions.
{% endif %}

For up-to-date documentation on Terminal Use, visit the [Terminal Use docs](https://docs.terminaluse.com/llms-full.txt).

## Features

{% if sdk_type == "codex_agent_sdk" %}
- **Codex-Powered**: Uses Codex to plan and execute coding steps
- **codex_tool Streaming**: Forwards Codex thread events to TerminalUse adapters
- **Multi-Turn Conversations**: Maintains Codex thread context across turns
- **Workspace Execution**: Runs Codex in `/workspace` by default
{% else %}
- **Claude-Powered**: Uses Claude to understand and respond to user requests
- **File Operations**: Can create, read, and edit files in the workspace
- **Multi-Turn Conversations**: Maintains session context across message turns
- **Tool Access**: Has access to Read, Write, Edit, Bash, Glob, and Grep tools
{% endif %}

## Key Concepts

- **Tasks**: A conversation thread or session with the agent
- **Messages**: User inputs and agent responses within a task
{% if sdk_type == "codex_agent_sdk" %}
- **Thread State**: Preserves conversation context across turns using Codex thread IDs
{% else %}
- **Session State**: Preserves conversation context across turns using session IDs
{% endif %}

## Deploy

Deploy your agent to the Terminal Use platform:

```bash
tu deploy
```

This builds and deploys your agent. Once deployed, you can interact with it via the platform.

## What's Inside

This template:
{% if sdk_type == "codex_agent_sdk" %}
- Sets up an ACP server that routes messages to Codex
- Uses OpenAI Agents `codex_tool` stream events and forwards them to TerminalUse raw events
- Maintains thread state for multi-turn conversations
- Includes Codex CLI in the generated Docker image (used by the `codex_tool` wrapper)
{% else %}
- Sets up an ACP server that routes messages to Claude
- Uses the Claude Agent SDK for intelligent conversation handling
- Maintains session state for multi-turn conversations
- Provides file and command execution capabilities out of the box
{% endif %}

## The Config File

The `config.yaml` file is your agent's configuration file. It defines:
- How your agent should be built and packaged
- What files are included in your agent's Docker image
- Your agent's name and description

This file is essential for deployment of your agent.

## Project Structure

```
{{ project_name }}/
├── src/                      # Your agent's code
│   ├── __init__.py
│   └── agent.py              # Agent server and event handlers
├── Dockerfile               # Container definition
├── config.yaml            # Deployment config
{% if use_uv %}
└── pyproject.toml          # Dependencies (uv)
{% else %}
└── requirements.txt         # Dependencies (pip)
{% endif %}
```

## Development

### Customize Event Handlers
- Modify the handlers in `agent.py` to implement your agent's logic
- Add your own tools and capabilities
- Implement custom state management

### Manage Dependencies

{% if use_uv %}
```bash
# Add new dependencies
uv add requests openai anthropic

# Install/sync dependencies
uv sync
```
{% else %}
```bash
# Edit requirements.txt manually to add dependencies
echo "requests" >> requirements.txt
echo "openai" >> requirements.txt

# Install dependencies
pip install -r requirements.txt
```
{% endif %}

### Configure Environment Variables

Use the CLI to manage environment variables for your deployed agent:

```bash
# Add an environment variable
tu env add MY_API_KEY --value "sk-..." --secret

# List environment variables
tu env ls

# Remove an environment variable
tu env rm MY_API_KEY
```

### Interact with Your Deployed Agent

```bash
# Create a task and send a message
tu tasks create --message "Your task here"

# Send a follow-up message to an existing task
tu tasks send <TASK_ID> --message "Follow-up message"

# List tasks
tu tasks ls

# View agent logs
tu logs
```

### Other Useful Commands

```bash
# List recent versions
tu ls

# Rollback to a previous version
tu rollback
```
