Python SDK Reference

The agentvisor Python SDK provides utilities for agents running inside AgentVisor™.

Availability

The AgentVisor SDK is automatically available in containerized execution. You can immediately use:

from agentvisor import checkpoint, store

Structured logging works out of the box with standard logging.getLogger(__name__) — no agentvisor import required. See Agent Logging for details, including the optional agentvisor.logging.get_logger() convenience wrapper.

For local development with --sandbox=none, see SDK Installation.

Overview

The SDK provides essential features for production agents including checkpointing, structured logging, key-value storage, and MCP integration:

Module	Purpose
langgraph	LangGraph integration (checkpointer, graph discovery)
checkpoint	Direct checkpoint API
stream	Emit stream chunks for real-time SSE delivery
store	Long-term memory, persists across runs and threads
state	Per-thread key-value state
mcp	MCP client integration
a2a	A2A agent communication
schema	@agent, @tool decorators and schema export
logging	Structured logging
tracing	OpenTelemetry span forwarding
langchain	LangChain integration (MCP/A2A tools)
config	Environment-based configuration (get_config())
retry	Automatic retry with exponential backoff

Core Utilities

Two functions underlie every module above — most agent code never calls them directly, but framework integrations and custom clients do:

from agentvisor.client import get_client
from agentvisor.config import get_config

client = get_client()  # the process-global AgentClient (gRPC connection)
config = get_config()  # Config(agent_socket, thread_id, run_id) from the environment

get_client() lazily constructs and caches a single AgentClient per process; get_config() reads AGENTVISOR_AGENT_SOCKET/AGENTVISOR_THREAD_ID/AGENTVISOR_RUN_ID from the environment once and caches the result. Neither raises immediately if called outside a running agent process — the gRPC channel underlying get_client() is built lazily, so the RuntimeError for a missing AGENTVISOR_AGENT_SOCKET only surfaces on the first actual call that needs the connection (checkpoint.save(), store.get(), etc.), not at get_client()/get_config() itself.

Basic Usage

LangGraph Checkpointer

from agentvisor.langgraph import AgentVisorCheckpointer
from langgraph.graph import StateGraph

builder = StateGraph(MyState)
# ... build graph ...

graph = builder.compile(checkpointer=AgentVisorCheckpointer())

Environment Variables

The SDK reads configuration from environment variables set by AgentVisor:

Variable	Description
AGENTVISOR_AGENT_SOCKET	Path to agent Unix socket
AGENTVISOR_THREAD_ID	Current thread ID
AGENTVISOR_RUN_ID	Current run ID
HTTP_PROXY	Proxy URL for HTTP requests

These are set automatically - you don't need to configure them.

Automatic Retry

The SDK automatically retries operations that encounter transient failures (network blips, rate limiting, timeouts). This happens transparently - your agent code doesn't need to handle these cases.

Transient errors that trigger retry:

• UNAVAILABLE - Service temporarily down
• DEADLINE_EXCEEDED - Request timeout
• RESOURCE_EXHAUSTED - Rate limiting

Retries use exponential backoff with jitter to prevent thundering herd problems.

# This automatically retries on transient failures
checkpoint.save("my-state", data)

# Configure retry behavior if needed
from agentvisor.retry import configure_retry, RetryConfig

configure_retry(checkpoint=RetryConfig(max_attempts=5, base_delay_ms=200))

See the Retry Mechanisms reference for configuration options and details.

Error Handling

SDK functions raise specific exceptions:

from agentvisor.client import StoreNotEnabledError

# Store operations raise StoreNotEnabledError if store not configured
try:
    from agentvisor import store
    store.put("ns", "key", {"value": 1})
except StoreNotEnabledError:
    print("Store API is not enabled on the host")

note

Transient gRPC errors (UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED) are automatically retried before being raised. Exceptions you catch have already exhausted their retry budget.