# test/test-agent - TerminalUse Starter Template

This is a generic starter template for building agents with the TerminalUse framework. It provides a basic implementation of the Agent 2 Client Protocol (ACP) to help you get started quickly.

## What You'll Learn

- **Tasks**: A task is a grouping mechanism for related messages. Think of it as a conversation thread or a session.
- **Messages**: Messages are communication objects within a task. They can contain text, data, or instructions.
- **ACP Events**: The agent responds to four main events:
  - `task_received`: When a new task is created
  - `task_message_received`: When a message is sent within a task
  - `task_approved`: When a task is approved
  - `task_canceled`: When a task is canceled

## Running the Agent

1. Run the agent locally:
```bash
terminaluse agents run --config config.yaml
```

The agent will start on port 8000 and print messages whenever it receives any of the ACP events.

## What's Inside

This template:
- Sets up a basic ACP server
- Handles each of the required ACP events with simple print statements
- Provides a foundation for building more complex agents

## Next Steps

For more advanced agent development, check out the TerminalUse tutorials:

- **Tutorials 00-08**: Learn about building synchronous agents with ACP
- **Tutorials 09-10**: Learn how to use Temporal to power asynchronous agents
  - Tutorial 09: Basic Temporal workflow setup
  - Tutorial 10: Advanced Temporal patterns and best practices

These tutorials will help you understand:
- How to handle long-running tasks
- Implementing state machines
- Managing complex workflows
- Best practices for async agent development

## 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
- Local development settings (like the port your agent runs on)

This file is essential for both local development and deployment of your agent.

## Project Structure

```
test_agent/
├── src/                      # Your agent's code
│   ├── __init__.py
│   └── agent.py              # Agent server and event handlers
├── Dockerfile               # Container definition
├── config.yaml            # Deployment config
├── dev.ipynb                # Development notebook for testing

└── pyproject.toml          # Dependencies (uv)

```

## Development

### 1. 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

### 2. Test Your Agent with the Development Notebook
Use the included `dev.ipynb` Jupyter notebook to test your agent interactively:

```bash
# Start Jupyter notebook (make sure you have jupyter installed)
jupyter notebook dev.ipynb

# Or use VS Code to open the notebook directly
code dev.ipynb
```

The notebook includes:
- **Setup**: Connect to your local TerminalUse backend
- **Task creation**: Create a new task for the conversation
- **Event sending**: Send events to the agent and get responses
- **Async message subscription**: Subscribe to server-side events to receive agent responses
- **Rich message display**: Beautiful formatting with timestamps and author information

The notebook automatically uses your agent name (`test/test-agent`) and demonstrates the async ACP workflow: create task → send event → subscribe to responses.

### 3. Manage Dependencies


You chose **uv** for package management. Here's how to work with dependencies:

```bash
# Add new dependencies
terminaluse uv add requests openai anthropic

# Install/sync dependencies
terminaluse uv sync

# Run commands with uv
uv run terminaluse agents run --config config.yaml
```

**Benefits of uv:**
- Faster dependency resolution and installation
- Better dependency isolation
- Modern Python packaging standards



### 4. Configure Credentials
Options:
1. Add any required credentials to your config.yaml via the `env` section
2. Export them in your shell: `export OPENAI_API_KEY=...`
3. For local development, create a `.env.local` file in the project directory

```python
import os
from dotenv import load_dotenv

if os.environ.get("ENVIRONMENT") == "development":
    load_dotenv()
```

## Local Development


### 1. Start the TerminalUse Backend
```bash
# Navigate to the backend directory
cd terminaluse

# Start all services using Docker Compose
make dev

# Optional: In a separate terminal, use lazydocker for a better UI (everything should say "healthy")
lzd
```

### 2. Setup Your Agent's requirements/pyproject.toml
```bash
terminaluse uv sync [--group editable-apy]
source .venv/bin/activate

# OR
conda create -n test_agent python=3.12
conda activate test_agent
pip install -r requirements.txt
```
### 3. Run Your Agent
```bash
# From this directory
export ENVIRONMENT=development && [uv run] terminaluse agents run --config config.yaml
```

### 4. Interact with Your Agent

Option 0: CLI (deprecated - to be replaced once a new CLI is implemented - please use the web UI for now!)
```bash
# Submit a task via CLI
terminaluse tasks submit --agent test/test-agent --task "Your task here"
```

Option 1: Web UI
```bash
# Start the local web interface
cd terminaluse-web
make dev

# Then open http://localhost:3000 in your browser to chat with your agent
```

## Development Tips

### Environment Variables
- Set environment variables in src/.env for any required credentials
- Or configure them in the config.yaml under the `env` section
- The `.env` file is automatically loaded in development mode

### To build the agent Docker image locally (normally not necessary):

1. Build the agent image:
```bash
terminaluse agents build --config config.yaml
```
