SDK Configuration
Client Options
Both Mutagent (sync) and AsyncMutagent (async) accept the same constructor arguments:
from mutagent import Mutagent, AsyncMutagent
import httpx
client = Mutagent(
api_key="mt_xxxxxxxxxxxx", # API key (sends x-api-key header); falls back to MUTAGENT_API_KEY env var
server_url="https://api.mutagent.io", # API endpoint; falls back to MUTAGENT_SERVER_URL env var (default: http://localhost:3003)
timeout=60.0, # Request timeout in seconds (default: 60)
http_client=httpx.Client(), # Optional custom httpx.Client
allow_insecure_http=False, # Set True to allow plain HTTP to non-local hosts
)
Authentication
The SDK reads your API key from the constructor or from the MUTAGENT_API_KEY environment variable. If neither is provided, requests will be sent without authentication (resulting in 401 responses).
API Key (Recommended)
from mutagent import Mutagent
# Simplest: SDK auto-reads MUTAGENT_API_KEY env var
client = Mutagent()
# Explicit: pass API key directly
client = Mutagent(api_key="mt_xxxxxxxxxxxx")
# With production server URL
client = Mutagent(
api_key="mt_xxxxxxxxxxxx",
server_url="https://api.mutagent.io",
)
Environment Variables
| Variable | Description | Default |
|---|
MUTAGENT_API_KEY | Your MutagenT API key | None (unauthenticated) |
MUTAGENT_SERVER_URL | API endpoint for the client | http://localhost:3003 |
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
MUTAGENT_SERVER_URL=https://api.mutagent.io
from mutagent import Mutagent
# No explicit args needed — env vars are auto-read
client = Mutagent()
The default server_url is http://localhost:3003 (local dev). For production, always set MUTAGENT_SERVER_URL=https://api.mutagent.io or pass it explicitly. The SDK enforces HTTPS for non-local hosts unless allow_insecure_http=True is passed.
Timeout Configuration
The timeout parameter is in seconds (not milliseconds):
from mutagent import Mutagent
client = Mutagent(
timeout=120.0, # 2 minutes
)
Context Manager (Recommended)
Use the client as a context manager to ensure the underlying HTTP connection pool is properly closed:
from mutagent import Mutagent
with Mutagent() as client:
prompts = client.prompt.list_prompts()
Async context manager
import asyncio
from mutagent import AsyncMutagent
async def main():
async with AsyncMutagent() as client:
prompts = await client.prompt.list_prompts()
asyncio.run(main())
Custom HTTP Client
For advanced use cases (proxies, custom TLS, request interceptors), provide your own httpx.Client:
import httpx
from mutagent import Mutagent
# Example: custom proxy
transport = httpx.HTTPTransport(proxy="http://proxy.example.com:8080")
custom_client = httpx.Client(transport=transport)
client = Mutagent(
http_client=custom_client,
)
import httpx
from mutagent import AsyncMutagent
async_client = httpx.AsyncClient(
headers={"X-Custom-Header": "value"},
)
client = AsyncMutagent(
http_client=async_client,
)
Namespace Reference
The client exposes these namespaces. Each namespace groups related API methods:
| Namespace | Access | Description |
|---|
prompt | client.prompt | Prompt CRUD and versioning |
prompt_datasets | client.prompt_datasets | Dataset management |
prompt_dataset_items | client.prompt_dataset_items | Dataset item management |
prompt_evaluations | client.prompt_evaluations | Evaluation management |
optimization | client.optimization | Optimization job control |
traces | client.traces | Trace ingestion and retrieval |
experiments | client.experiments | Experiment management |
organizations | client.organizations | Organization management |
workspaces | client.workspaces | Workspace management |
