### Copy Environment Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/coding_agents/README.md

Copy the example environment file to start configuring your agent and platform settings.

```bash
cp .env.example .env
```

--------------------------------

### Complete Agent Usage Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/agent.md

A full example demonstrating the setup and execution of an Agent. It includes necessary imports, adapter configuration, agent creation, and running the agent with interrupt handling. This serves as a reference for integrating the Agent into a larger application.

```python
from __future__ import annotations

import asyncio
import logging

logging.basicConfig(level=logging.INFO)

from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

from thenvoi import Agent
from thenvoi.adapters import LangGraphAdapter

async def main() -> None:
    adapter = LangGraphAdapter(
        llm=ChatOpenAI(model="gpt-4o-mini"),
        checkpointer=InMemorySaver(),
    )
    
    agent = Agent.create(
        adapter=adapter,
        agent_id="550e8400-e29b-41d4-a716-446655440000",
        api_key="sk_test...",
    )
    
    # Run until interrupted (SIGINT)
    try:
        await agent.run(shutdown_timeout=30)
    except KeyboardInterrupt:
        print("Shutting down...")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Agent.start

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/agent.md

Start the agent. Initializes the platform connection, calls adapter setup callbacks, and begins listening for events.

```APIDOC
## Agent.start

### Description
Start the agent. Initializes the platform connection, calls adapter setup callbacks, and begins listening for events.

1. Initializes runtime (fetches agent metadata via REST API)
2. Calls `adapter.on_started()` with agent name and description
3. Connects WebSocket and begins event processing

### Method Signature
```python
async def start(self) -> None
```

### Parameters
None

### Returns
`None`

### Raises
- `ThenvoiConnectionError`: If WebSocket connection fails
- `ThenvoiConfigError`: If agent metadata cannot be retrieved

### Example
```python
agent = Agent.create(adapter=adapter, agent_id="...", api_key="...")
await agent.start()
try:
    await agent.run_forever()
finally:
    await agent.stop()
```
```

--------------------------------

### Quick Start: Initialize and Run Claude Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk/README.md

Initializes a basic Claude Agent using the ClaudeSDKAdapter and runs it. This example demonstrates the fundamental setup for agent creation and execution.

```python
from thenvoi import Agent
from thenvoi.adapters import ClaudeSDKAdapter

adapter = ClaudeSDKAdapter(
    # Omit `model` to use the npm `claude` binary's default, or pass a
    # family alias ("sonnet" / "opus" / "haiku").
    custom_section="You are a helpful assistant.",
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-id",
    api_key="your-api-key",
)
await agent.run()
```

--------------------------------

### Quick Start: Basic Agent with PydanticAIAdapter

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/pydantic_ai/README.md

A minimal setup for creating an agent using PydanticAIAdapter. This example shows how to initialize the adapter with a model and custom instructions, then create and run the agent.

```python
from thenvoi import Agent
from thenvoi.adapters import PydanticAIAdapter

adapter = PydanticAIAdapter(
    model="openai:gpt-5.4-mini",
    custom_section="You are a helpful assistant.",
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-id",
    api_key="your-api-key",
)
await agent.run()
```

--------------------------------

### Quick Start: Parlant Adapter with Thenvoi Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/parlant/README.md

This example shows the minimal setup for creating a Parlant agent with guidelines and integrating it with the Thenvoi SDK using the ParlantAdapter. No separate HTTP server is required.

```python
import parlant.sdk as p
from thenvoi import Agent
from thenvoi.adapters import ParlantAdapter

async with p.Server() as server:
    # Create Parlant agent with guidelines
    parlant_agent = await server.create_agent(
        name="Assistant",
        description="A helpful assistant.",
    )

    await parlant_agent.create_guideline(
        condition="User asks for help",
        action="Acknowledge their request and provide detailed assistance",
    )

    # Create Thenvoi adapter
    adapter = ParlantAdapter(
        server=server,
        parlant_agent=parlant_agent,
    )

    # Create and run agent
    agent = Agent.create(
        adapter=adapter,
        agent_id="your-agent-id",
        api_key="your-api-key",
    )
    await agent.run()
```

--------------------------------

### Install Dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/a2a_bridge/README.md

Installs the necessary dependencies for the A2A bridge examples using uv.

```bash
uv sync --extra a2a
```

--------------------------------

### Run the Quickstart Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Executes the Python quickstart agent script using uv.

```bash
uv run python quickstart_agent.py
```

--------------------------------

### Install Bridge Dependencies and Run

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/agentcore/README.md

Install bridge dependencies using 'uv sync' and then start the bridge using 'uv run'. Alternatively, run the module directly using 'PYTHONPATH'. Ensure dependencies are installed before running.

```bash
# Install bridge deps
uv sync --extra bridge_agentcore

# Start the bridge (loads .env automatically)
uv run python examples/agentcore/run_agentcore.py
# or run the module directly:
PYTHONPATH=thenvoi-bridge uv run python -m bridge_core
```

--------------------------------

### Copy Example Agents Configuration

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/mixed/README.md

Copy the example agents configuration file to be used for the mixed agent setup. This file will store credentials for the different agents.

```bash
cp examples/mixed/agents.yaml.example examples/mixed/agents.yaml
```

--------------------------------

### Copy Example Configuration Files

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Copy the example environment and agent configuration files to their active versions. These files are used to set up credentials and settings for running examples.

```bash
cp .env.example .env
cp agent_config.yaml.example agent_config.yaml
```

--------------------------------

### Run Basic CrewAI Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README.md

Execute the basic CrewAI agent setup script. This is the quickest way to verify Thenvoi and model credentials.

```bash
uv run examples/crewai/01_basic_agent.py
```

--------------------------------

### Quick Start Agent Creation

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/langgraph/README.md

Minimal setup for creating a LangGraph agent with Thenvoi. Requires an LLM and a checkpointer.

```python
from thenvoi import Agent
from thenvoi.adapters import LangGraphAdapter
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

# Create adapter with LLM and checkpointer
adapter = LangGraphAdapter(
    llm=ChatOpenAI(model="gpt-5.4-mini"),
    checkpointer=InMemorySaver(),
)

# Create and run agent
agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-id",
    api_key="your-api-key",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
    rest_url="https://app.thenvoi.com",
)
await agent.run()
```

--------------------------------

### Run Custom Instructions Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/pydantic_ai/README.md

Command to run the agent example with custom instructions using uv.

```bash
uv run python examples/pydantic_ai/02_custom_instructions.py
```

--------------------------------

### Quick Start Agent Creation

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/anthropic/README.md

Minimal setup for creating a Thenvoi agent using the Anthropic SDK with default settings. Ensure ANTHROPIC_API_KEY is set and dependencies are installed.

```python
from thenvoi import Agent
from thenvoi.adapters import AnthropicAdapter

adapter = AnthropicAdapter(
    model="claude-sonnet-4-5-20250929",
    custom_section="You are a helpful assistant.",
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-id",
    api_key="your-api-key",
)
await agent.run()
```

--------------------------------

### Install Multiple Adapters

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/adapters.md

Install multiple adapters simultaneously by listing them within the brackets.

```bash
uv add "thenvoi-sdk[langgraph,anthropic]"
```

--------------------------------

### Quick Start: Initialize LangGraph Adapter and Thenvoi Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/langgraph.md

Initialize the LangGraphAdapter with a LangChain LLM and checkpointer, then create a Thenvoi Agent. This example uses ChatOpenAI and an in-memory checkpointer.

```python
import asyncio

from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

from thenvoi import Agent
from thenvoi.adapters import LangGraphAdapter

adapter = LangGraphAdapter(
    llm=ChatOpenAI(model="gpt-5.4-mini"),
    checkpointer=InMemorySaver(),
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-uuid",
    api_key="your-thenvoi-api-key",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
    rest_url="https://app.thenvoi.com",
)

asyncio.run(agent.run())
```

--------------------------------

### Run Basic Agent with Docker Compose

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk/README.md

Starts the basic agent example using Docker Compose. Ensure environment variables are set or available in a .env file.

```bash
# Navigate to the claude_sdk example directory
cd examples/claude_sdk

# Set environment variables (or use .env file)
export THENVOI_AGENT_ID="your-agent-id"
export THENVOI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# Run the basic agent
docker compose up 01-basic

# Run the extended thinking example
docker compose up 02-extended-thinking
```

--------------------------------

### Basic Gateway Startup

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/a2a_gateway/README.md

Starts the A2A gateway to expose Thenvoi peers as A2A endpoints. Useful for initial setup and peer discovery.

```bash
uv run examples/a2a_gateway/01_basic_gateway.py
```

--------------------------------

### Quick Start: Initialize and Run Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/codex.md

Initialize the CodexAdapter with configuration and create a Thenvoi Agent. Then, run the agent to start the collaboration.

```python
import asyncio
import os

from thenvoi import Agent
from thenvoi.adapters.codex import CodexAdapter, CodexAdapterConfig

adapter = CodexAdapter(
    config=CodexAdapterConfig(
        cwd=os.getcwd(),
        model="gpt-5.2",
    ),
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-uuid",
    api_key="your-thenvoi-api-key",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
    rest_url="https://app.thenvoi.com",
)

asyncio.run(agent.run())
```

--------------------------------

### Run Basic Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/pydantic_ai/README.md

Command to run the basic agent example script using uv.

```bash
uv run python examples/pydantic_ai/01_basic_agent.py
```

--------------------------------

### Complete ThenvoiLink Usage Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/thenvoi_link.md

A comprehensive example demonstrating connection, room subscription, and event handling within a main asynchronous function. Includes graceful shutdown on KeyboardInterrupt.

```python
from __future__ import annotations

import asyncio
from thenvoi import ThenvoiLink
from thenvoi.platform import PlatformEvent, MessageEvent, RoomAddedEvent

async def main() -> None:
    link = ThenvoiLink(
        agent_id="550e8400-e29b-41d4-a716-446655440000",
        api_key="sk_test...",
    )
    
    await link.connect()
    await link.subscribe_agent_rooms(link.agent_id)
    
    try:
        async for event in link:
            match event:
                case RoomAddedEvent(room_id=rid):
                    print(f"Joined room: {rid}")
                    await link.subscribe_room(rid)
                
                case MessageEvent(payload=msg, room_id=rid):
                    print(f"[{msg.sender_name}]: {msg.content}")
                    
                case _:
                    print(f"Event: {event.type}")
    except KeyboardInterrupt:
        await link.disconnect()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run Toy Router Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README_flow_adapter.md

Execute the toy router example to observe decision shapes, parallel delegation, sequential handoff, and synthesis behavior without relying on an LLM.

```bash
uv run examples/crewai/08_flow_router.py
```

--------------------------------

### Install LangGraph Adapter

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/adapters.md

Install the LangGraph adapter as an optional dependency using uv.

```bash
uv add "thenvoi-sdk[langgraph]"
```

--------------------------------

### Run Coordinator CrewAI Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README.md

Execute the coordinator agent example script. This example is useful for validating CrewAI and Thenvoi tool cooperation in a room workflow.

```bash
uv run examples/crewai/03_coordinator_agent.py
```

--------------------------------

### Install Codex Adapter

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/codex.md

Install the Thenvoi SDK with Codex support using uv.

```bash
uv add "thenvoi-sdk[codex]"
```

--------------------------------

### Run Parlant Examples

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/parlant/README.md

Execute the Parlant example Python scripts from the project root directory using uv. Ensure agent_config.yaml is in the current working directory.

```bash
# From project root
cd /path/to/thenvoi-sdk-python

# Run examples
uv run python examples/parlant/01_basic_agent.py
uv run python examples/parlant/02_with_guidelines.py
uv run python examples/parlant/03_support_agent.py
```

--------------------------------

### Copy Agent Configuration Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/coding_agents/README.md

Copy the example agent configuration file to define your planner and reviewer agents, including repository details.

```bash
cp agent_config.yaml.example agent_config.yaml
```

--------------------------------

### Complete Event Loop Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/events.md

A comprehensive example demonstrating how to initialize ThenvoiLink, connect, subscribe to agent rooms and contacts, and process various platform events within an asynchronous loop. Includes handling room lifecycle, messages, participants, and contact requests.

```python
from __future__ import annotations

import asyncio
from thenvoi import ThenvoiLink
from thenvoi.platform import (
    PlatformEvent,
    MessageEvent,
    RoomAddedEvent,
    RoomRemovedEvent,
    ParticipantAddedEvent,
    ParticipantRemovedEvent,
    ContactRequestReceivedEvent,
    ContactAddedEvent,
)

async def main() -> None:
    link = ThenvoiLink(
        agent_id="550e8400-e29b-41d4-a716-446655440000",
        api_key="sk_test...",
    )
    
    await link.connect()
    
    # Subscribe to events
    await link.subscribe_agent_rooms(link.agent_id)
    await link.subscribe_agent_contacts(link.agent_id)
    
    try:
        async for event in link:
            await handle_platform_event(event, link)
    except KeyboardInterrupt:
        await link.disconnect()

async def handle_platform_event(event: PlatformEvent, link: ThenvoiLink) -> None:
    """Handle platform events."""
    match event:
        # Room lifecycle
        case RoomAddedEvent(room_id=rid, payload=room):
            print(f"✓ Joined room {rid}: {room.title or 'Untitled'}")
            await link.subscribe_room(rid)
        
        case RoomRemovedEvent(room_id=rid):
            print(f"✗ Left room {rid}")
        
        # Messages
        case MessageEvent(room_id=rid, payload=msg):
            print(f"[{rid}] {msg.sender_name}: {msg.content}")
        
        # Participants
        case ParticipantAddedEvent(room_id=rid, payload=p):
            print(f"  + {p.name} ({p.type}) joined")
        
        case ParticipantRemovedEvent(room_id=rid, payload=p):
            print(f"  - {p.id} left")
        
        # Contacts
        case ContactRequestReceivedEvent(payload=req):
            print(f"📬 Contact request from {req.from_name}: {req.message}")
        
        case ContactAddedEvent(payload=contact):
            print(f"👤 New contact: {contact.name} (@{contact.handle})")
        
        # Other
        case _:
            print(f"Event: {event.type}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run Basic Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk/README.md

Executes the basic agent example script. This command assumes the script is located at 'examples/claude_sdk/01_basic_agent.py'.

```bash
python examples/claude_sdk/01_basic_agent.py
```

--------------------------------

### Run Contact and Memory CrewAI Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README.md

Execute the CrewAI example that exercises contact tools and enables memory tools in the adapter. This example demonstrates how contact changes appear as room context.

```bash
uv run examples/crewai/07_contact_and_memory_agent.py
```

--------------------------------

### Install Thenvoi Claude SDK

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/claude_sdk.md

Install the Thenvoi SDK with Claude SDK support using uv.

```bash
uv add "thenvoi-sdk[claude_sdk]"
```

--------------------------------

### Install Thenvoi SDK with Pip

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Install the Thenvoi SDK with the 'langgraph' extra using pip. This command is equivalent to the uv installation for pip users.

```bash
pip install "thenvoi-sdk[langgraph]"
```

--------------------------------

### Install Thenvoi SDK with ACP

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/AGENTS.md

Install the thenvoi-sdk with the ACP extra or add it using uv.

```bash
pip install thenvoi-sdk[acp]
# or
uv add thenvoi-sdk[acp]
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk_docker/README.md

Example YAML configuration for a single agent, including required credentials and optional settings for model, prompt, and tools.

```yaml
agent_id: "agt_abc123xyz"  # Your Agent ID from Thenvoi
api_key: "sk_live_..."     # Your API Key from Thenvoi
```

--------------------------------

### Installing thenvoi-sdk with claude-sdk extra

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/MIGRATING-v0.3.0.md

The claude-sdk has moved to an optional extra. Install it using pip or uv if you are using ClaudeSDKAdapter.

```bash
pip install thenvoi-sdk[claude-sdk]
```

```bash
uv add thenvoi-sdk[claude-sdk]
```

--------------------------------

### Running Anthropic Examples

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/anthropic/README.md

Commands to execute the Anthropic SDK examples for Thenvoi using `uv run`. Ensure you are in the repository root.

```bash
# From repository root
uv run python examples/anthropic/01_basic_agent.py
uv run python examples/anthropic/02_custom_instructions.py
```

--------------------------------

### Run Basic A2A Bridge Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/a2a_bridge/README.md

Execute the basic A2A bridge example from the repository root. This ensures that the script uses the local checkout of the thenvoi-sdk.

```bash
uv run examples/a2a_bridge/01_basic_agent.py
```

--------------------------------

### Install Dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/CONTRIBUTING.md

Install project dependencies, including development tools, using the uv package manager.

```bash
uv sync --extra dev
```

--------------------------------

### Install Anthropic Adapter

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/anthropic.md

Install the Thenvoi SDK with Anthropic support using pip or uv.

```bash
uv add "thenvoi-sdk[anthropic]"
```

--------------------------------

### Install Parlant SDK with Optional Dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/parlant/README.md

Install the Parlant SDK for Python, including optional dependencies for enhanced functionality.

```bash
pip install 'thenvoi-sdk[parlant]'
```

--------------------------------

### Install Thenvoi SDK with Parlant Support

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/parlant/README.md

Install the Thenvoi SDK including Parlant support using uv. Alternatively, sync with the extra from a repository.

```bash
uv add "git+https://github.com/thenvoi/thenvoi-sdk-python.git[parlant]"
```

```bash
uv sync --extra parlant
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/CONTRIBUTING.md

Install pre-commit hooks to automatically check code style and quality before commits.

```bash
uv run pre-commit install
```

--------------------------------

### Run Extended Thinking Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk/README.md

Executes the extended thinking agent example script. This command assumes the script is located at 'examples/claude_sdk/02_extended_thinking.py'.

```bash
python examples/claude_sdk/02_extended_thinking.py
```

--------------------------------

### Start Game Script

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/20-questions-arena/README.md

Initiates a 20 Questions game by creating a chat room, adding the Thinker and configured Guessers, and sending a start message. Requires your user API key.

```bash
uv run examples/20-questions-arena/start_game.py <your-user-api-key>
```

--------------------------------

### Run Role-Based CrewAI Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README.md

Execute the role-based agent example script. This demonstrates setting up an agent with a role, goal, and backstory.

```bash
uv run examples/crewai/02_role_based_agent.py
```

--------------------------------

### LangGraphAdapter Constructor Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/adapters.md

Instantiate LangGraphAdapter with a LangChain LLM and a LangGraph checkpointer. This example uses the simple pattern for connecting to LangGraph.

```python
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver
from thenvoi.adapters import LangGraphAdapter
from thenvoi import Agent

adapter = LangGraphAdapter(
    llm=ChatOpenAI(model="gpt-4o-mini"),
    checkpointer=InMemorySaver(),
    custom_section="You are a helpful assistant.",
)

agent = Agent.create(
    adapter=adapter,
    agent_id="...",
    api_key="...",
)
```

--------------------------------

### Complete Thenvoi Agent Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/INDEX.md

A comprehensive example demonstrating how to configure a LangGraph adapter, session behavior, and contact handling strategy to create and run a Thenvoi agent.

```python
from __future__ import annotations

import asyncio
import logging

logging.basicConfig(level=logging.INFO)

from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

from thenvoi import Agent, SessionConfig
from thenvoi.adapters import LangGraphAdapter
from thenvoi.runtime.types import ContactEventConfig, ContactEventStrategy
from thenvoi.platform.event import ContactRequestReceivedEvent

async def main() -> None:
    # Configure adapter
    adapter = LangGraphAdapter(
        llm=ChatOpenAI(model="gpt-4o-mini"),
        checkpointer=InMemorySaver(),
    )
    
    # Configure session behavior
    session_config = SessionConfig(
        enable_context_cache=True,
        max_context_messages=100,
    )
    
    # Configure contact handling
    async def auto_approve(event, tools):
        if isinstance(event, ContactRequestReceivedEvent):
            await tools.respond_contact_request(
                "approve",
                request_id=event.payload.id,
            )
    
    contact_config = ContactEventConfig(
        strategy=ContactEventStrategy.CALLBACK,
        on_event=auto_approve,
    )
    
    # Create and run agent
    agent = Agent.create(
        adapter=adapter,
        agent_id="550e8400-e29b-41d4-a716-446655440000",
        api_key="sk_test_...",
        session_config=session_config,
        contact_config=contact_config,
    )
    
    try:
        await agent.run(shutdown_timeout=30)
    except KeyboardInterrupt:
        print("\nShutting down...")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Install Thenvoi SDK with Adapters

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/INDEX.md

Install the base Thenvoi SDK package or with specific adapters like LangGraph, Anthropic, or Pydantic-AI. Use '[dev]' for all adapters except Parlant.

```bash
# Base package only
uv add "thenvoi-sdk"

# With LangGraph adapter
uv add "thenvoi-sdk[langgraph]"

# With multiple adapters
uv add "thenvoi-sdk[langgraph,anthropic,pydantic_ai]"

# With all adapters (except parlant - conflicts with crewai)
uv add "thenvoi-sdk[dev]"
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/CONTRIBUTING.md

Copy the example environment file and edit it with your specific configuration.

```bash
cp .env.example .env
# Edit .env with your configuration
```

--------------------------------

### Install Thenvoi SDK with ACP support

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/CLAUDE.md

Install the SDK with optional dependencies for ACP integration. This command includes the 'agent-client-protocol' package.

```bash
pip install thenvoi-sdk[acp]
```

```bash
uv add thenvoi-sdk[acp]
```

--------------------------------

### Run Basic Bridge Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/a2a_bridge/README.md

Executes the basic A2A bridge example, suitable for agents that do not require authentication. Ensure A2A_AGENT_URL is set.

```bash
export A2A_AGENT_URL=http://localhost:10000
uv run examples/a2a_bridge/01_basic_agent.py
```

--------------------------------

### Install Thenvoi SDK from Repository with Pydantic AI

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/pydantic_ai/README.md

Alternatively, install the Thenvoi SDK with Pydantic AI support directly from the repository using uv sync.

```bash
uv sync --extra pydantic_ai
```

--------------------------------

### Run Example Agents with UV

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Execute example Python scripts using the 'uv run' command. This allows you to test different framework integrations like 'langgraph', 'pydantic_ai', 'anthropic', and 'codex'.

```bash
uv run python examples/run_agent.py --example langgraph
```

```bash
uv run python examples/run_agent.py --example pydantic_ai
```

```bash
uv run python examples/run_agent.py --example anthropic
```

```bash
uv run python examples/run_agent.py --example codex
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/anthropic/README.md

Example YAML configuration for Anthropic agents, including agent ID and API key. This is used for setting up credentials.

```yaml
anthropic_agent:
  agent_id: "your-agent-id"
  api_key: "your-thenvoi-api-key"

support_agent:
  agent_id: "your-agent-id"
  api_key: "your-thenvoi-api-key"
```

--------------------------------

### Run Authenticated Bridge Example with API Key

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/a2a_bridge/README.md

Executes the authenticated A2A bridge example using an API key for authentication. Set A2A_AGENT_URL and A2A_API_KEY.

```bash
export A2A_AGENT_URL=http://localhost:10000
export A2A_API_KEY=your-api-key
uv run examples/a2a_bridge/02_with_auth.py
```

--------------------------------

### REST API - Get Agent Metadata

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/thenvoi_link.md

Example of retrieving agent metadata using the REST client's agent API.

```python
# Get agent metadata
agent = await link.rest.agent_api_agents.get_agent(agent_id)
```

--------------------------------

### Quick Start Thenvoi Agent with Claude SDK Adapter

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/claude_sdk.md

Initialize and run a Thenvoi agent using the Claude SDK adapter. Ensure Claude Code is installed and authenticated, and provide your Thenvoi API key and agent UUID.

```python
import asyncio
import os

from thenvoi import Agent
from thenvoi.adapters import ClaudeSDKAdapter

adapter = ClaudeSDKAdapter(
    cwd=os.getcwd(),
    approval_mode="manual",
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-uuid",
    api_key="your-thenvoi-api-key",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
    rest_url="https://app.thenvoi.com",
)

asyncio.run(agent.run())
```

--------------------------------

### Install Thenvoi SDK Dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/AGENTS.md

Commands to install dependencies for the thenvoi SDK using uv. Includes installing all extras except parlant, and separately for parlant.

```bash
# Install dependencies (all extras except parlant — see Dependency Conflicts below)
uv sync --extra dev

# Install parlant adapter deps (isolated from dev/crewai)
uv sync --extra dev-parlant
```

--------------------------------

### Agent Initialization (Full Composition)

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/agent.md

Demonstrates the full composition pattern for initializing the Agent class. This is suitable for advanced users requiring custom runtime or preprocessing. Ensure all necessary imports are included.

```python
from thenvoi import Agent
from thenvoi.runtime.platform_runtime import PlatformRuntime
from thenvoi.adapters import LangGraphAdapter
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

runtime = PlatformRuntime(
    agent_id="my-agent-uuid",
    api_key="my-api-key",
)
adapter = LangGraphAdapter(
    llm=ChatOpenAI(model="gpt-4o-mini"),
    checkpointer=InMemorySaver(),
)
agent = Agent(runtime=runtime, adapter=adapter)
await agent.start()
```

--------------------------------

### Run Tom and Jerry CrewAI Character Examples

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README.md

Execute the Tom and Jerry character-style agent examples in separate terminals. These examples showcase CrewAI's behavior with personality-heavy prompts.

```bash
uv run examples/crewai/05_tom_agent.py
uv run examples/crewai/06_jerry_agent.py
```

--------------------------------

### Install CrewAI and Parlant Extras

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Use this command to install the 'crewai' and 'parlant' extras for the Thenvoi SDK. Note that these two extras cannot be installed in the same environment due to mutually exclusive transitive dependencies.

```bash
uv add "thenvoi-sdk[crewai,parlant]"
```

--------------------------------

### Initializing Agent with from_config

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/MIGRATING-v0.3.0.md

A new convenience factory, Agent.from_config(), allows loading agent credentials from a YAML configuration file, simplifying agent setup.

```python
from thenvoi import Agent

agent = Agent.from_config(
    "researcher",
    adapter=AnthropicAdapter(...),
)
await agent.run()
```

--------------------------------

### Install Thenvoi SDK with Pydantic AI Support

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/pydantic_ai/README.md

Install the Thenvoi SDK with Pydantic AI capabilities and a model provider like OpenAI. Ensure you also install the specific provider package.

```bash
uv add "git+https://github.com/thenvoi/thenvoi-sdk-python.git[pydantic_ai]"

# Plus your model provider:
pip install "pydantic-ai-slim[openai]"  # or [anthropic], [google], etc.
```

--------------------------------

### Copy Configuration Files

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/parlant/README.md

Copy example configuration files for environment variables and agent settings from the project root.

```bash
# From project root
cp .env.example .env
cp agent_config.yaml.example agent_config.yaml
```

--------------------------------

### Install ACP Optional Dependency

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/AGENTS.md

Install the ACP integration for the thenvoi-sdk. This includes the agent-client-protocol.

```toml
[project.optional-dependencies]
acp = ["agent-client-protocol"]
```

--------------------------------

### Python Quickstart Agent using LangGraph

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Creates a LangGraph agent using the Thenvoi SDK. This script initializes the adapter, creates the agent with provided credentials, and runs it. It requires OPENAI_API_KEY, QUICKSTART_AGENT_ID, and QUICKSTART_API_KEY to be set as environment variables.

```python
from __future__ import annotations

import asyncio
import logging
import os

logging.basicConfig(level=logging.INFO)

from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

from thenvoi import Agent
from thenvoi.adapters import LangGraphAdapter


async def main() -> None:
    adapter = LangGraphAdapter(
        llm=ChatOpenAI(model=os.getenv("OPENAI_MODEL", "gpt-5.4-mini")),
        checkpointer=InMemorySaver(),
    )

    agent = Agent.create(
        adapter=adapter,
        agent_id=os.environ["QUICKSTART_AGENT_ID"],
        api_key=os.environ["QUICKSTART_API_KEY"],
    )

    await agent.run()


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Copy Environment File

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk_docker/README.md

Copies the example environment file to a new file named .env. This is the first step in configuring your environment.

```bash
cp .env.example .env
# Edit .env - add your ANTHROPIC_API_KEY
```

--------------------------------

### Install CrewAI Dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/crewai/README.md

Install CrewAI dependencies from the repository root using the provided command.

```bash
uv sync --extra crewai
```

--------------------------------

### Install Dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/mixed/README.md

Install the necessary Python dependencies for the project, including crewai and a2a extras.

```bash
uv sync --extra crewai --extra a2a
```

--------------------------------

### Run Conformance Tests

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/CLAUDE.md

Execute conformance tests for framework configurations, adapter conformance, and converter conformance. Replace '<framework>' with the specific framework name.

```bash
uv run pytest tests/framework_conformance/test_config_drift.py -v
uv run pytest tests/framework_conformance/test_adapter_conformance.py -v -k "<framework>"
uv run pytest tests/framework_conformance/test_converter_conformance.py -v -k "<framework>"
```

--------------------------------

### Install A2A Bridge

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Install the A2A bridge integration for interoperability with external A2A-compliant agents.

```bash
uv add "thenvoi-sdk[a2a]"
```

--------------------------------

### Custom Adapter Implementation

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/adapters.md

Example of creating a custom adapter by extending SimpleAdapter. This includes implementing lifecycle methods like on_started, on_event, and on_cleanup, and handling agent input and tool usage.

```python
from thenvoi.core.simple_adapter import SimpleAdapter
from thenvoi.core.types import AdapterFeatures

class MyAdapter(SimpleAdapter):
    def __init__(self, model, features=None):
        super().__init__()
        self.model = model
        self.features = features or AdapterFeatures()
    
    async def on_started(self, agent_name: str, agent_description: str) -> None:
        """Called when agent starts."""
        pass
    
    async def on_event(self, inp: AgentInput) -> None:
        """Handle incoming message from platform."""
        # Convert history
        history = inp.history.convert(my_converter)
        
        # Call LLM with tools
        response = await self.model.invoke(
            messages=history,
            tools=inp.tools,
        )
        
        # Use tools as needed
        if should_send_message:
            await inp.tools.send_message(
                content="...",
                mentions=["@alice"],
            )
    
    async def on_cleanup(self, room_id: str) -> None:
        """Called when room is cleaned up."""
        pass

# Use the adapter
agent = Agent.create(
    adapter=MyAdapter(model=my_llm),
    agent_id="...",
    api_key="...",
)
```

--------------------------------

### Set Environment Variables for Quickstart Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Exports necessary API keys and agent IDs as environment variables. Ensure you replace the placeholder values with your actual credentials.

```bash
export QUICKSTART_AGENT_ID="paste-agent-uuid-here"
export QUICKSTART_API_KEY="paste-agent-api-key-here"
export OPENAI_API_KEY="paste-openai-api-key-here"
```

--------------------------------

### Initialize Claude SDK Adapter with Features

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/claude_sdk.md

Demonstrates how to initialize the Claude SDK Adapter with custom capabilities and telemetry emission settings. Ensure necessary imports are included.

```python
import os

from thenvoi import AdapterFeatures, Capability, Emit
from thenvoi.adapters import ClaudeSDKAdapter

adapter = ClaudeSDKAdapter(
    cwd=os.getcwd(),
    features=AdapterFeatures(
        capabilities={Capability.CONTACTS, Capability.MEMORY},
        emit={Emit.EXECUTION, Emit.THOUGHTS},
    ),
)
```

--------------------------------

### Install A2A Gateway

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Install the A2A gateway integration to expose Thenvoi peers as A2A JSON-RPC endpoints.

```bash
uv add "thenvoi-sdk[a2a_gateway]"
export GATEWAY_AGENT_ID="your-gateway-agent-id"
export GATEWAY_API_KEY="your-gateway-api-key"
```

--------------------------------

### Install and Login to Codex CLI

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/codex.md

Install the Codex CLI globally and log in to your OpenAI account. Requires Node.js 18+.

```bash
npm install -g @openai/codex
codex login
```

--------------------------------

### Install parlant adapter dependencies

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/CLAUDE.md

Installs dependencies specifically for the parlant adapter. This is isolated from other development dependencies to avoid conflicts.

```bash
uv sync --extra dev-parlant
```

--------------------------------

### Build and Run Basic Agent with Docker Directly

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk/README.md

Builds a Docker image for the Claude SDK example and runs the basic agent. It passes necessary environment variables for Thenvoi and Anthropic API keys.

```bash
# Build from project root
docker build -f examples/claude_sdk/Dockerfile -t claude-sdk-example .

# Run the basic agent
docker run --rm \
  -e THENVOI_AGENT_ID="your-agent-id" \
  -e THENVOI_API_KEY="your-api-key" \
  -e ANTHROPIC_API_KEY="your-anthropic-api-key" \
  -e THENVOI_REST_URL="${THENVOI_REST_URL:-}" \
  -e THENVOI_WS_URL="${THENVOI_WS_URL:-}" \
  claude-sdk-example
```

--------------------------------

### Install and Authenticate Claude Code

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/docs/adapters/claude_sdk.md

Install the Claude Code CLI globally and log in to authenticate your environment. Requires Node.js 20+.

```bash
npm install -g @anthropic-ai/claude-code
claude auth login
```

--------------------------------

### Create Agent with Default Settings

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/agent.md

Use `Agent.create` for straightforward agent instantiation. Provide necessary adapter, agent ID, and API key. Optional parameters allow customization of URLs and callbacks.

```python
from thenvoi import Agent
from thenvoi.adapters import LangGraphAdapter
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

adapter = LangGraphAdapter(
    llm=ChatOpenAI(model="gpt-4o-mini"),
    checkpointer=InMemorySaver(),
)
agent = Agent.create(
    adapter=adapter,
    agent_id="550e8400-e29b-41d4-a716-446655440000",
    api_key="sk_test_...",
    rest_url="https://app.thenvoi.com",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
)
```

--------------------------------

### Start Thinker Agent

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/20-questions-arena/README.md

Initiates the Thinker agent, which acts as the game master. It waits for a user to create a room and start a game.

```bash
uv run examples/20-questions-arena/thinker_agent.py
```

--------------------------------

### Install ACP Integration

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/README.md

Install the ACP integration to enable editors like Cursor and Zed to communicate with Thenvoi agents via stdio.

```bash
uv add "thenvoi-sdk[acp]"
export ACP_AGENT_ID="your-acp-agent-id"
export ACP_API_KEY="your-acp-api-key"
thenvoi-acp --agent-id "$ACP_AGENT_ID" --api-key "$ACP_API_KEY"
```

--------------------------------

### Run Demo Orchestrator with Gateway

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/a2a_gateway/README.md

Starts the gateway on port 10000 and a local demo A2A orchestrator on port 10001. Requires OPENAI_API_KEY to be set.

```bash
export OPENAI_API_KEY=your-openai-key
uv run examples/a2a_gateway/02_with_demo_agent.py
```

--------------------------------

### Complete Agent Configuration Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/_autodocs/configuration.md

This snippet shows how to configure and run a Thenvoi agent with all available settings, including adapter, agent runtime, session behavior, and contact handling.

```python
from __future__ import annotations

import asyncio
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

from thenvoi import Agent, AgentConfig, SessionConfig
from thenvoi.adapters import LangGraphAdapter
from thenvoi.runtime.types import ContactEventConfig, ContactEventStrategy
from thenvoi.platform.event import ContactRequestReceivedEvent

async def main() -> None:
    # Configure adapter
    adapter = LangGraphAdapter(
        llm=ChatOpenAI(model="gpt-4o-mini"),
        checkpointer=InMemorySaver(),
    )
    
    # Configure agent runtime
    agent_config = AgentConfig(
        auto_subscribe_existing_rooms=True,
    )
    
    # Configure session behavior
    session_config = SessionConfig(
        enable_context_cache=True,
        context_cache_ttl_seconds=300,
        max_context_messages=100,
        max_message_retries=1,
        idle_resync_seconds=60.0,
    )
    
    # Configure contact handling
    async def auto_approve(event, tools):
        if isinstance(event, ContactRequestReceivedEvent):
            await tools.respond_contact_request("approve", request_id=event.payload.id)
    
    contact_config = ContactEventConfig(
        strategy=ContactEventStrategy.CALLBACK,
        on_event=auto_approve,
        broadcast_changes=True,
    )
    
    # Create agent with all configurations
    agent = Agent.create(
        adapter=adapter,
        agent_id="550e8400-e29b-41d4-a716-446655440000",
        api_key="sk_test_...",
        config=agent_config,
        session_config=session_config,
        contact_config=contact_config,
    )
    
    # Run the agent
    await agent.run(shutdown_timeout=30)

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install Python Dependencies for Claude SDK

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk/README.md

Installs the Thenvoi SDK with the necessary 'claude_sdk' extras. This can be done using 'uv' for dependency management.

```bash
# Install with claude_sdk extras
uv add "git+https://github.com/thenvoi/thenvoi-sdk-python.git[claude_sdk]"

# Or from repository
uv sync --extra claude_sdk
```

--------------------------------

### Agent Configuration with Optional Settings

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/claude_sdk_docker/README.md

A detailed example of an agent configuration file, showing required credentials and optional parameters like model selection, prompt customization, and tool definitions.

```yaml
# Required: credentials from Thenvoi Dashboard
agent_id: "agt_abc123xyz"
api_key: "sk_live_..."

# Optional: customize your agent.  Omit `model` to use the npm `claude`
# binary's default; aliases like `opus` / `sonnet` / `haiku` resolve to the
# latest of that family.  `fallback_model` is used by the binary when the
# primary model is unavailable.
# model: opus
# fallback_model: sonnet
prompt: |
  You are a helpful assistant that specializes in customer support.
  Be friendly, concise, and always offer to help further.
tools:
  - calculator
  - get_time

# Optional: extended thinking (requires Sonnet 4.5+ or any Opus)
# thinking_tokens: 10000
```

--------------------------------

### Weather Agent System Prompt Example

Source: https://github.com/thenvoi/thenvoi-sdk-python/blob/main/examples/agentcore/BUILDING.md

A concrete example of a system prompt for a weather agent, detailing its behavior, response style, and limitations.

```text
Behaviour
- Provide current temperature and basic weather conditions for cities by name.
- Reply only to messages that explicitly @-mention you with a weather question.
- When you reply, always @-mention whoever asked you.

Style
- Be concise. One short sentence per data point is fine.
- If a city is ambiguous or unrecognised, ask for clarification rather than guess.

Out of scope
- Do not initiate conversations.
- Do not coordinate with other agents — answer the asker directly.
```