Agent

In shortReference for the Agent class: constructor parameters, providers, retry and fallback, reasoning, memory, multimodal limits, and common errors.

  • 8 min read
  • 10 sections
  • Updated
  • v0.10.0
  • Markdown

The Agent class is a graph node that calls an LLM through the native OpenAI, Google, or Anthropic SDK. It handles message conversion, tool calls, memory retrieval, skills, streaming, and retries for you. Add it to a StateGraph as a node, and the graph supplies state and routing.

Import path

Python
from tenxgraph.core.graph import Agent, RetryConfig, StateGraph, ToolNode

Agent

Initializes an LLM-calling graph node for use in a StateGraph.

Signature

Python
def __init__(
    self,
    model: str,
    output_type: str = "text",
    system_prompt: list[dict[str, Any]] | None = None,
    tool_node: str | ToolNode | None = None,
    extra_messages: list[Message] | None = None,
    trim_context: bool = False,
    tools_tags: set[str] | None = None,
    reasoning_config: dict[str, Any] | bool | None = {"effort": "medium"},
    skills: SkillConfig | None = None,
    memory: MemoryConfig | None = None,
    retry_config: RetryConfig | bool | None = True,
    fallback_models: list[str | tuple[str, str]] | None = None,
    multimodal_config: MultimodalConfig | None = None,
    output_schema: type[BaseModel] | None = None,
    **kwargs,
) -> None

Parameters

Parameter Type Default Description
model str required Model identifier. Examples: "gpt-4o", "gemini-2.5-flash", "claude-sonnet-5". A recognized provider prefix (openai/, gpt/, google/, gemini/, anthropic/, claude/) selects the provider and is stripped. Any other name is sent as is to the OpenAI-compatible client.
provider str | None None (via kwargs) Provider name: "openai", "google", "anthropic". If omitted, inferred from model name.
output_type str "text" Output modality: "text", "image", "video", "audio", or "json" (legacy, prefer output_schema). Support depends on the provider: Anthropic allows only "text" and "json", OpenAI has no "video".
system_prompt list[dict] | None None System prompt as list of message dicts: [{"role": "system", "content": "..."}]. Supports state field interpolation with {field_name} placeholders filled from the state at run time.
tool_node str | ToolNode | None None Tools for the agent. Pass a ToolNode instance or a string naming a graph node whose func is a ToolNode. Resolved at execution time.
extra_messages list[Message] | None None Additional messages prepended to context before each LLM call.
trim_context bool False Trim conversation history to fit within the model’s context window.
tools_tags set[str] | None None Filter ToolNode tools by tag. Only tools with matching tags are offered to the LLM.
api_style str "chat" (via kwargs) OpenAI API style: "chat" (Chat Completions) or "responses" (Responses API). Any other value raises ValueError.
reasoning_config dict | bool | None {"effort": "medium"} Reasoning config for models supporting extended thinking. True enables defaults, False or None disables, a dict sets model-specific options. See Reasoning models.
skills SkillConfig | None None Agent Skills configuration per agentskills.io spec. Injects skill catalog and activation/read tools. See skills.
memory MemoryConfig | None None Long-term memory config for retrieving relevant context before each LLM call. See Memory.
retry_config RetryConfig | bool | None True Retry logic for transient API errors. True uses defaults; False or None disables; pass RetryConfig for tuning. See Retry configuration.
fallback_models list[str | tuple[str, str]] | None None Ordered fallback models to try if primary exhausts retries. Each entry: model string (inherits provider) or (model, provider) tuple.
multimodal_config MultimodalConfig | None None Image and document handling limits for multimodal requests. See media.
output_schema type[BaseModel] | None None Pydantic model that the final text output must conform to. Not allowed with "image", "video", or "audio" output.
use_vertex_ai bool False (via kwargs) Google provider only. Route Gemini through Vertex AI instead of Gemini API. Defaults to true when GOOGLE_GENAI_USE_VERTEXAI=true. For Claude it selects the Vertex backend.
base_url str | None None (via kwargs) Base URL for OpenAI-compatible APIs (Ollama, vLLM, OpenRouter, DeepSeek, etc.).
**kwargs any none Additional provider-specific parameters: temperature, max_tokens, top_p, top_k, organization_id, project_id, etc.

Returns

None. The constructor builds the node. When the graph runs it, the agent reads the state, calls the model, and appends the response to the message list.

Raises

Exception Condition
ImportError Required provider SDK not installed (e.g., google-genai, openai, anthropic packages).
ValueError output_type is not supported by the resolved provider, output_schema is combined with image, video, or audio output, api_style is not "chat" or "responses", or an explicit provider is not google, openai, or anthropic.

Example

Python
from tenxgraph.core.graph import Agent, StateGraph, ToolNode
from tenxgraph.utils import END

# Define tools (set OPENAI_API_KEY and install "10xgraph[openai]" first)
def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"Sunny in {location}"

def get_time() -> str:
    """Get current time."""
    return "3:00 PM"

# Create agent with tools
tool_node = ToolNode([get_weather, get_time])
agent = Agent(
    model="gpt-4o",
    system_prompt=[{"role": "system", "content": "You are a helpful assistant."}],
    tool_node=tool_node,
)

# Use in a graph
graph = StateGraph()
graph.add_node("MAIN", agent)
graph.add_node("TOOL", tool_node)
graph.set_entry_point("MAIN")

# Route: call tools if requested, else end
def should_continue(state):
    last = state.context[-1]
    if last.role == "assistant" and getattr(last, "tools_calls", None):
        return "TOOL"
    return END

graph.add_conditional_edges("MAIN", should_continue, {"TOOL": "TOOL", END: END})
graph.add_edge("TOOL", "MAIN")

app = graph.compile()

Supported providers

Provider Backend Models
"openai" OpenAI API gpt-4o, gpt-4o-mini, o1, o3, o4-mini, plus OpenAI-compatible models via base_url
"google" Gemini API or Vertex AI gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash
"anthropic" Claude API (direct, Vertex AI, or Bedrock) claude-* models, for example claude-sonnet-5

The "google" provider supports both Gemini API and Vertex AI. Toggle Vertex AI with use_vertex_ai=True on the agent or set GOOGLE_GENAI_USE_VERTEXAI=true.

Provider inference

If provider is omitted, the library infers it from the model string, after stripping a recognized provider/ prefix:

Model name Provider
Starts with claude- or anthropic. "anthropic"
Starts with gemini-, imagen-, veo-, or chirp "google"
Starts with gpt-, o1-, o3-, or o4- "openai"
Anything else "openai" (logged at info level)

With use_vertex_ai=True, every non-Claude model resolves to "google". Pass provider explicitly for names that do not match, such as provider="google" for a custom Gemini deployment.

For Anthropic, the anthropic_backend kwarg selects the backend: None (direct Claude API, default), "vertex" (Vertex AI), or "bedrock" (AWS Bedrock). Bedrock model IDs keep the anthropic. prefix.


Retry configuration

By default, Agent retries transient API errors (429, 500, 502, 503, 529) with exponential back-off. Configure with retry_config:

Python
from tenxgraph.core.graph.agent_internal.constants import RetryConfig

# Enable with defaults
agent = Agent(model="gpt-4o", retry_config=True)

# Customize retry behavior
agent = Agent(
    model="gpt-4o",
    retry_config=RetryConfig(
        max_retries=5,
        initial_delay=2.0,
        max_delay=60.0,
        backoff_factor=2.0,
    ),
)

# Disable retries
agent = Agent(model="gpt-4o", retry_config=False)

RetryConfig fields

Field Default Description
max_retries 3 Attempts against the primary model before trying fallbacks.
initial_delay 1.0 Seconds before the first retry.
max_delay 30.0 Upper bound on exponential back-off delay.
backoff_factor 2.0 Multiplier after each retry.
retryable_status_codes {429, 500, 502, 503, 529} HTTP status codes treated as transient.
circuit_breaker_enabled False Track consecutive failures per (provider, model) pair and skip open circuits.
circuit_breaker_threshold 5 Consecutive failures that open a circuit.
circuit_breaker_reset_timeout 30.0 Seconds a circuit stays open before retrying.

When circuit_breaker_enabled=True, consecutive failures to a (provider, model) pair open its circuit, causing calls to skip it and try the next fallback for circuit_breaker_reset_timeout seconds. After the timeout, one trial is allowed; success closes the circuit.

Python
agent = Agent(
    model="gpt-4o",
    fallback_models=["gpt-4o-mini"],
    retry_config=RetryConfig(
        circuit_breaker_enabled=True,
        circuit_breaker_threshold=5,
        circuit_breaker_reset_timeout=30.0,
    ),
)

Reasoning models

Reasoning-capable models (for example OpenAI o-series and Gemini thinking models) are controlled with reasoning_config. Reasoning is on by default at medium effort:

Python
# Enable reasoning with default effort
agent = Agent(model="o4-mini", reasoning_config=True)

# Disable reasoning (False or None)
agent = Agent(model="o4-mini", reasoning_config=False)

# OpenAI: effort level
agent = Agent(model="o4-mini", reasoning_config={"effort": "high"})

# Google: explicit thinking budget (tokens)
agent = Agent(model="gemini-2.5-pro", reasoning_config={"thinking_budget": 8000})

effort applies to all providers, summary is OpenAI-only, and thinking_budget is Google-only and overrides effort. For Gemini, effort maps to a budget: "low" is 512 tokens, "medium" is 8192 (default), "high" is 24576.


Fallback models

When the primary model fails (after exhausting retries), try fallbacks in order:

Python
agent = Agent(
    model="gpt-4o",
    fallback_models=[
        "gpt-4o-mini",                    # same provider
        ("gemini-2.5-flash", "google"),   # explicit provider
    ],
)

Memory-augmented agent

Pass a MemoryConfig as memory to give the agent long-term memory. Here my_qdrant_store stands for a BaseStore you have created (see the memory stores reference):

Python
from tenxgraph.storage.store import MemoryConfig, ReadMode

memory_config = MemoryConfig(
    store=my_qdrant_store,
    retrieval_mode=ReadMode.POSTLOAD,
    limit=5,
)

agent = Agent(
    model="gpt-4o",
    system_prompt=[{"role": "system", "content": "You are a helpful assistant."}],
    memory=memory_config,
)

# Provide the store when compiling the graph
app = graph.compile(store=my_qdrant_store)

retrieval_mode is a ReadMode: NO_RETRIEVAL, PRELOAD, or POSTLOAD (the MemoryConfig default). With POSTLOAD, the agent also exposes user and agent memory tools to the model. MemoryConfig fields are store, retrieval_mode, limit, score_threshold, max_tokens, inject_system_prompt, config, user_memory, and agent_memory. Defaults: limit=5, score_threshold=0.0, inject_system_prompt=True. See memory-stores for details.


Multimodal config

Use multimodal_config to limit image and document processing for multimodal requests:

Python
from tenxgraph.storage.media.config import MultimodalConfig

agent = Agent(
    model="gpt-4o",
    multimodal_config=MultimodalConfig(
        max_image_size_mb=10.0,
        max_image_dimension=2048,
    ),
)

MultimodalConfig fields: image_handling ("base64", "url", or "file_id"; default "base64"), document_handling ("extract_text", "pass_raw", or "skip"; default "extract_text"), max_image_size_mb (default 10.0), max_image_dimension (default 2048), supported_image_types, and supported_doc_types.


Common errors

Error Cause Fix
AuthenticationError Missing or invalid API key. Set OPENAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, or Vertex AI credentials. See Models and providers and provider troubleshooting.
ValueError: GOOGLE_CLOUD_PROJECT environment variable must be set Vertex AI enabled without a GCP project. Export GOOGLE_CLOUD_PROJECT and ensure Application Default Credentials are configured.
ImportError: google-genai SDK is required Google provider extra not installed. Install: pip install "10xgraph[google-genai]" or pip install google-genai.
ImportError: openai SDK is required OpenAI provider extra not installed. Install: pip install "10xgraph[openai]" or pip install openai.
ImportError: anthropic SDK is required Anthropic provider extra not installed. Install: pip install "10xgraph[anthropic]" or pip install anthropic.
ValueError: Invalid api_style api_style is not "chat" or "responses". Use one of the two supported values.
ValueError: ... doesn't support output_type The provider cannot generate that output, for example image output on Anthropic. Use a provider that supports it, or switch to output_type="text".

Last updated for v0.10.0Edit this page on GitHubReport an issue