# {{ agent_name }} - Temporal Agent Template

This template creates an asynchronous agent powered by the Claude Agent SDK and Temporal. It provides an implementation of the Agent Client Protocol (ACP) with Temporal workflow support for long-running, stateful operations.

## Features

- **Claude-Powered**: Uses Claude to understand and respond to user requests
- **Temporal Workflows**: Long-running processes with complex state management and async operations
- **ACP Events**: Responds to `task_received`, `task_message_received`, `task_approved`, and `task_canceled` events
- **File Operations**: Can create, read, and edit files in the workspace

## 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:
- Sets up an ACP server with Temporal integration
- Handles each of the required ACP events
- Provides a foundation for building complex async agents
- Includes Temporal workflow and activity definitions

## 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
- Temporal worker configuration

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
│   ├── workflow.py           # Temporal workflow definitions
│   └── run_worker.py         # Temporal worker setup
├── 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

### Develop Temporal Workflows
- Edit `workflow.py` to define your agent's async workflow logic
- Modify `activities.py` to add custom activities
- Use `run_worker.py` to configure the Temporal worker

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

## Advanced Features

### Temporal Workflows
Extend your agent with sophisticated async workflows:

```python
# In src/workflow.py
@workflow.defn
class MyWorkflow(BaseWorkflow):
    async def complex_operation(self):
        # Multi-step async operations
        # Error handling and retries
        # State management
        pass
```

### Custom Activities
Add custom activities for external operations. **Important**: Always specify appropriate timeouts (recommended: 10 minutes):

```python
# In src/activities.py
from datetime import timedelta
from temporalio import activity
from temporalio.common import RetryPolicy

@activity.defn(name="call_external_api")
async def call_external_api(data):
    # HTTP requests, database operations, etc.
    pass

# In your workflow, call it with a timeout:
result = await workflow.execute_activity(
    "call_external_api",
    data,
    start_to_close_timeout=timedelta(minutes=10),  # Recommended: 10 minute timeout
    heartbeat_timeout=timedelta(minutes=1),         # Optional: heartbeat monitoring
    retry_policy=RetryPolicy(maximum_attempts=3)    # Optional: retry policy
)

# Don't forget to register your custom activities in run_worker.py:
# all_activities = get_all_activities() + [your_custom_activity_function]
```
