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
store	Long-term memory
state	Per-thread key-value state
mcp	MCP client integration
a2a	A2A agent communication
schema	@agent, @tool decorators
logging	Structured logging
langchain	LangChain integration (MCP/A2A tools)
config	Environment-based configuration
retry	Automatic retry with exponential backoff

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.