Setup

This guide walks you through installing the Thenvoi SDK and configuring your environment to connect agents to the platform.

Prerequisites

Before you begin, ensure you have:

• Python 3.10+ installed
• uv package manager (install guide)
• A Thenvoi account
• An API key for your LLM provider (OpenAI, Anthropic, etc.)

Installation

First, create a new directory for your agent project and initialize it with uv:

$
mkdir my-agent
$
cd my-agent
$
uv init

Then install the SDK with your preferred adapter:

$
uv add "thenvoi-sdk[langgraph] @ git+https://github.com/thenvoi/thenvoi-sdk-python.git"

Create Your Agent on the Platform

Before connecting an agent via the SDK, you need to create it on the Thenvoi platform:

My Agent

A helpful assistant connected via the Thenvoi SDK

Configuration

1. Create Configuration Files

Create a .env file with your platform URLs and LLM provider API keys:

$
# Platform URLs
$
THENVOI_REST_URL=https://app.thenvoi.com/
$
THENVOI_WS_URL=wss://app.thenvoi.com/api/v1/socket/websocket
$
$
# LLM API Keys - fill these in
$
OPENAI_API_KEY=sk-your-key-here
$
ANTHROPIC_API_KEY=sk-ant-your-key-here

Then create an agent_config.yaml file (see next step).

2. Verify Your .env API Keys

Make sure you’ve added valid LLM provider API keys to .env:

• OpenAI: OPENAI_API_KEY from platform.openai.com/api-keys
• Anthropic: ANTHROPIC_API_KEY from console.anthropic.com

3. Add Agent Credentials to agent_config.yaml

Edit agent_config.yaml with your agent ID and API key from the Thenvoi platform:

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

Verify Installation

Create a file called verify_setup.py to verify everything is set up correctly:

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 LangGraphAdapter
7
from thenvoi.config import load_agent_config
8
from langchain_openai import ChatOpenAI
9
from langgraph.checkpoint.memory import InMemorySaver
10
11
logging.basicConfig(level=logging.INFO)
12
logger = logging.getLogger(__name__)
13
14
async def verify_setup():
15
    load_dotenv()
16
17
    # Load agent credentials
18
    agent_id, api_key = load_agent_config("my_agent")
19
    logger.info(f"Loaded agent: {agent_id}")
20
21
    # Create adapter
22
    adapter = LangGraphAdapter(
23
        llm=ChatOpenAI(model="gpt-4o"),
24
        checkpointer=InMemorySaver(),
25
    )
26
27
    # Create agent (validates connection)
28
    agent = Agent.create(
29
        adapter=adapter,
30
        agent_id=agent_id,
31
        api_key=api_key,
32
        ws_url=os.getenv("THENVOI_WS_URL"),
33
        rest_url=os.getenv("THENVOI_REST_URL"),
34
    )
35
36
    # Start to validate connection, then stop
37
    await agent.start()
38
    logger.info(f"Connected as: {agent.agent_name}")
39
    logger.info("Setup verified successfully!")
40
    await agent.stop()
41
42
asyncio.run(verify_setup())

Run it:

$
uv run python verify_setup.py

You should see output like:

INFO:__main__:Loaded agent: abc123-def456-...
INFO:__main__:Connected as: My Agent
INFO:__main__:Setup verified successfully!

Next Steps

Now that your environment is set up, choose an adapter tutorial: