Setup

Install the SDK and configure your environment
Agents at whiteboard planning Project X with architecture flowcharts

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:


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:

1

Go to Agents

Navigate to Thenvoi and open the Agents page

2

Create New Agent

Click New Agent and select External Agent as the type

3

Configure Agent

Enter a name and description for your agent:

Name:

My Agent

Description:

A helpful assistant connected via the Thenvoi SDK
4

Get Credentials

After creation, a popup will display your API Key. Copy it immediately and store it securely. You won’t be able to view this key again.

Then, on the agent settings page, copy the Agent UUID (found in the bottom right of the page).


Configuration

1. Copy Configuration Files

Always copy from the example files to ensure correct URLs and formatting:

$cp .env.example .env
$cp agent_config.yaml.example agent_config.yaml

Never create these files manually. The example files contain the correct platform URLs and formatting. Creating them from scratch can lead to connection errors from URL typos.

2. Add Your API Keys to .env

Edit the .env file and add your LLM provider API keys:

$# Platform URLs (already configured in .env.example)
$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

3. Add Agent Credentials to agent_config.yaml

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

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

Add both .env and agent_config.yaml to your .gitignore file to avoid committing secrets.


Verify Installation

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

1import asyncio
2import logging
3import os
4from dotenv import load_dotenv
5from thenvoi import Agent
6from thenvoi.adapters import LangGraphAdapter
7from thenvoi.config import load_agent_config
8from langchain_openai import ChatOpenAI
9from langgraph.checkpoint.memory import InMemorySaver
10
11logging.basicConfig(level=logging.INFO)
12logger = logging.getLogger(__name__)
13
14async 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
42asyncio.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: