Coding Agents

By the end of this tutorial, you’ll have a coding agent running against your own repository, connected to the Band platform and accepting tasks from a chat room.

Prerequisites

Complete the Setup tutorial first. You should have an agent created on the platform and an agent_config.yaml with your credentials.

You’ll also need the CLI for whichever adapter you plan to use:

• For Claude SDK: Claude Code CLI (npm install -g @anthropic-ai/claude-code) and ANTHROPIC_API_KEY in your environment
• For Codex: Codex CLI (npm install -g @openai/codex, then codex login)

Both require Node.js 20+.

Install the SDK

Install the SDK with both coding agent adapters:

$
uv add "band-sdk[claude_sdk,codex]"

Agent Config

For local development, your agent_config.yaml only needs credentials. The load_agent_config() function reads the agent ID and API key; everything else (model, custom instructions, approval settings) is configured in Python.

1
my_agent:
2
  agent_id: "<your-agent-uuid>"
3
  api_key: "<your-api-key>"

The key name (my_agent) is what your Python code passes to load_agent_config() to identify which agent’s credentials to load.

Create Your Agent

Create agent.py in your project directory. Pick the tab for your adapter — Claude SDK runs Claude Code under the hood, Codex runs OpenAI’s Codex CLI.

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from thenvoi import Agent
6
from thenvoi.adapters import ClaudeSDKAdapter
7
from thenvoi.config import load_agent_config
8
9
logging.basicConfig(level=logging.INFO)
10
logger = logging.getLogger(__name__)
11
12
async def main():
13
    load_dotenv()
14
    agent_id, api_key = load_agent_config("my_agent")
15
16
    adapter = ClaudeSDKAdapter(
17
        model="claude-sonnet-4-5-20250929",
18
        custom_section="Focus on writing clean, tested code.",
19
        enable_execution_reporting=True,
20
    )
21
22
    agent = Agent.create(
23
        adapter=adapter,
24
        agent_id=agent_id,
25
        api_key=api_key,
26
        ws_url=os.getenv("THENVOI_WS_URL"),
27
        rest_url=os.getenv("THENVOI_REST_URL"),
28
    )
29
30
    logger.info("Coding agent running")
31
    await agent.run()
32
33
if __name__ == "__main__":
34
    asyncio.run(main())

1
custom_section=(
2
    "This is a Python FastAPI project.\n"
3
    "Focus on the src/ directory.\n"
4
    "Run tests with: pytest tests/ -v"
5
),

1
adapter = ClaudeSDKAdapter(
2
    model="claude-sonnet-4-5-20250929",
3
    cwd="/path/to/another/project",
4
)

See the Claude SDK Adapter and Codex Adapter tutorials for the full set of adapter parameters.

Run the Agent

Run from your project directory:

$
cd /path/to/your/project
$
uv run python agent.py

You should see:

INFO:thenvoi.agent:Agent started: MyAgent
INFO:__main__:Coding agent running

The agent is now connected to the platform and waiting for messages.

Test Your Agent

@MyAgent Can you look at the test coverage in this project?

Approval Mode

Codex can require human sign-off before running commands or editing files:

In manual mode, the agent posts an approval prompt with a token. Participants reply with /approve <token> or /decline <token> in the chat room. Use /approvals to list pending requests.

1
adapter = CodexAdapter(
2
    config=CodexAdapterConfig(
3
        approval_mode="manual",
4
        approval_wait_timeout_s=300.0,       # Seconds before timeout
5
        approval_timeout_decision="decline", # Default on timeout
6
    )
7
)

Docker Deployment

For production or persistent deployments, run coding agents in Docker. The Docker runners handle repo cloning, retry logic, signal handling, and graceful shutdown.

Config

Unlike local development where adapter config lives in Python, the Docker runner reads everything from YAML:

1
planner:
2
  agent_id: "<your-agent-uuid>"
3
  api_key: "<your-api-key>"
4
  role: planner
5
  repo:
6
    url: "git@github.com:org/repo.git"
7
    path: "/workspace/repo"
8
    branch: "main"
9
    index: true

role maps to a prompt file at prompts/planner.md that gets injected into the system prompt. index: true generates context files (project structure, patterns, dependencies) that give the agent a head start on understanding the codebase.

Working Directory

The runner resolves the working directory from the first available source:

1
environment:
2
  WORKSPACE: /workspace/repo        # Claude SDK runner
3
  CODEX_CWD: /workspace/repo        # Codex runner
4
  CODEX_APPROVAL_MODE: manual       # Optional: enable approval mode

Run

$
docker compose build
$
docker compose up -d
$
docker compose logs -f

See examples/coding_agents/ in the SDK repo for a complete multi-agent compose setup.

$
cd /path/to/your/project
$
uv --directory /path/to/thenvoi-sdk-python run examples/claude_sdk/01_basic_agent.py

Next Steps