10xGraphv0.10.0Search

    Reference

    In this sectionReference for 10xGraph: the Python library, the REST and WebSocket API, the CLI and 10xgraph.json configuration, and the typed TypeScript client.

    • 56 pages
    • About 474 min to read all

    The 10xGraph reference documents four surfaces of one system: the Python library, the REST and WebSocket API that the server generates from your graph, the CLI with its 10xgraph.json configuration, and the TypeScript client. It is for developers who already know what they want to call and need exact signatures, options and error conditions. Pick the surface you are calling from.

    Start here

    Python developers should open Graph and Agent first: they define StateGraph, CompiledGraph, invoke, stream and how a model is wired into a node. Checkpointers matters for production, because durable threads and replay-safe tool calls depend on one.

    If you run the server, the CLI commands and configuration pages cover every 10xgraph.json key, with auth and rate limiting for the production settings. Frontend developers should start with the client and stream pages. The REST contract starts at conventions and the graph endpoints.

    If you do not yet know which call you need, the guides are organized by task.

    Python library

    The graph engine, agents, tools, state, storage, and the evaluation harness. Everything importable from tenxgraph.*. The agentflow import is a deprecated alias until version 2.0; use tenxgraph in new code. The A2A protocol bridge is not available yet.

    Core building blocks

    Page Covers
    Graph StateGraph, CompiledGraph, nodes, edges, START, END, compile, invoke, stream
    Agent Agent, BaseAgent, ToolNode, how a model is wired into a node
    State AgentState, state type hints, reducers
    Messages Message, content blocks, message reducers

    Tools and control flow

    Page Covers
    Tools ToolNode, tool metadata, ToolResult, MCP integration
    Control flow Command, interrupt(), handoff, conditional routing
    Callbacks CallbackManager and invoke callbacks
    Lifecycle callbacks GraphLifecycleHook, on_graph_start, on_graph_end, on_graph_error

    State and memory

    Page Covers
    Checkpointers InMemoryCheckpointer, SqliteCheckpointer, PgCheckpointer, durability
    Memory stores Cross-thread memory, vector backends, search
    Context manager MessageContextManager, SummaryContextManager, context trimming

    Streaming and I/O

    Page Covers
    Stream emitter StreamEmitter and streaming events from inside tools
    Media MediaRef, MultimodalConfig, media storage backends

    LLM and observability

    Page Covers
    LLM call_llm, provider detection, client creation, timeouts
    Publishers Event publishers for streaming and observability
    ID generator Custom ID generation for distributed systems
    Runtime utilities Graceful shutdown, logging, message conversion, metrics

    Advanced

    Page Covers
    Exceptions GraphError, NodeError, GraphRecursionError, StaleStateError
    Prebuilt agents Constructor options for all agent types
    Prebuilt tools Fetch, file, search, calculator and memory tools
    Background tasks Long-running tasks during graph execution
    Adapters Convert OpenAI, Google GenAI and Anthropic responses to Message
    Realtime Realtime audio I/O
    Skills Load Agent Skills into agents

    Testing and evaluation

    Page Covers
    Testing TestAgent, QuickTest, MockToolRegistry, MockMCPClient
    Evaluation EvalSet, EvalCase, EvalCaseResult, EvalReport
    Evaluation criteria Every criterion class and how to choose one
    Evaluation harness Pytest helpers, batch runners and reporters

    REST and WebSocket API

    What the API server exposes once you run 10xgraph api.

    The server generates its own OpenAPI schema, so the authoritative contract for your build is always available locally:

    Surface Default path Setting
    Swagger UI http://127.0.0.1:8000/docs DOCS_PATH
    ReDoc http://127.0.0.1:8000/redocs REDOCS_PATH
    OpenAPI JSON http://127.0.0.1:8000/openapi.json On while either DOCS_PATH or REDOCS_PATH is set

    Set both DOCS_PATH and REDOCS_PATH to empty values in production to turn off the interactive docs and the raw schema at /openapi.json.

    Page Covers
    Conventions HTTP contract, error shape, status codes
    Graph /v1/graph/invoke, /v1/graph/stream, /v1/graph/stop, /v1/graph/fix
    Live WebSocket /v1/graph/live for bidirectional streams and realtime audio
    Threads /v1/threads, conversation history and management
    Memory store /v1/store, cross-thread memory operations
    Files /v1/files, upload, download and signed URLs
    Config /v1/config/multimodal, server configuration
    Observability /v1/observability/{thread_id}, run inspection
    Evals /v1/evals/runs, evaluation runs
    AG-UI /v1/ag-ui, AG-UI protocol
    Ping /ping, health checks

    CLI and configuration

    Page Covers
    Commands init, api, play, dev, build, config, eval, test, skills, audit, demo, version
    Configuration Every 10xgraph.json key and per-environment overrides
    Environment Every environment variable the server reads
    Auth JWT configuration and custom BaseAuth extension
    Rate limiting Rate limit backends and configuration

    TypeScript client

    The 10xgraph-client package, framework-agnostic and fully typed.

    Basics

    Page Covers
    Client Construction, options, and authentication
    Invoke Synchronous agent invocation
    Stream Event streaming and NDJSON chunks

    State and threads

    Page Covers
    Threads Thread creation and history
    Graph Graph information and utilities
    Message Message type definitions

    Features

    Page Covers
    Memory Long-term memory operations
    Files File upload and multimodal content
    Realtime Realtime audio sessions
    Auth Authentication options
    Errors Error classes and error handling

    Errors

    Page Covers
    Error codes Full catalog of error codes and causes

    Conventions used here

    • Signatures are the real ones. If a page and the source disagree, the source is right and the page is a bug. Please report it.
    • Defaults are stated explicitly, including when the default is None.
    • Error codes are listed with the condition that raises them. The full index is in error codes.

    Reference pages describe what things are. For task-shaped questions, start from the guides.

    All pages in Reference

    Python library

    1. GraphReference for StateGraph, CompiledGraph, Node, Edge, BaseAgent and RemoteToolConfig: signatures, parameters, returns, config keys and errors.14 min
    2. AgentReference for the Agent class: constructor parameters, providers, retry and fallback, reasoning, memory, multimodal limits, and common errors.8 min
    3. ToolsToolNode, ToolResult, and utilities for tool registration and execution.6 min
    4. StateReference for AgentState, ExecutionState, ExecutionStatus and the reducer functions in tenxgraph.core.state, with signatures, fields and examples.7 min
    5. MessagesReference for Message, the twelve content block types, MediaRef, AnnotationRef and TokenUsages, the typed format for all agent communication.9 min
    6. Context ManagerReference for MessageContextManager, SummaryContextManager and BaseContextManager, which trim or summarize message history before each LLM call.7 min
    7. LLM UtilitiesProvider detection, LLM client creation, batch processing, and timeout controls from tenxgraph.core.llm.11 min
    8. SkillsSkillConfig, SkillMeta, SkillDiagnostic, SkillResourceError and SkillsRegistry. Load Agent Skills into agents.11 min
    9. Realtime audioPython API reference for live audio-to-audio agent sessions with Gemini Live, including AudioAgent, RealtimeConfig, LiveInputQueue and RealtimeEvent.14 min
    10. StreamEmitterReference for StreamEmitter, the object injected into tools during streaming that sends live progress, error and message chunks to the caller.6 min
    11. ExceptionsException hierarchy for graph execution, storage, timeouts, and media validation errors.10 min
    12. Control flowReference for Command, interrupt(), Interrupt, GraphInterrupt, pending_interrupt, create_handoff_tool and is_handoff_tool in 10xGraph.8 min
    13. Callback ManagerReference for CallbackManager, InvocationType, CallbackContext, the three callback base classes, and the prompt injection and message validators.7 min
    14. Lifecycle CallbacksGraphLifecycleHook, GraphLifecycleContext - hook into graph-level events (start, end, error, interrupt, resume, checkpoint, state update).6 min
    15. Background Task ManagerReference for BackgroundTaskManager: create, track, wait for, cancel and shut down fire-and-forget asyncio tasks from node functions.5 min
    16. ID GeneratorBaseIDGenerator, IDType and the built-in generators: control the format of the thread IDs, run IDs and message IDs that 10xGraph creates.7 min
    17. Runtime utilitiesShutdown, logging, async helpers, message conversion, tool metadata, and metrics instrumentation.9 min
    18. PublishersReference for EventModel, BasePublisher, the Console, Redis, Kafka, RabbitMQ, OTEL, Logfire and LangSmith publishers, and publish_event.15 min
    19. Response adaptersConvert LLM responses from OpenAI, Google GenAI, and Anthropic to 10xGraph Message format.5 min
    20. CheckpointersCheckpointer implementations for state persistence. BaseCheckpointer, InMemoryCheckpointer, PgCheckpointer, SqliteCheckpointer.8 min
    21. Memory storesReference for BaseStore, QdrantStore, Mem0Store, embedding classes, MemoryConfig, MemoryIntegration, preload helpers and store factories.17 min
    22. MediaHandle images, audio, video, and documents in agent messages. Offload large blobs, validate content, process images, cache uploads.13 min
    23. Prebuilt agentsAPI reference for built-in agent patterns: ReactAgent, RAGAgent, PlanActReflectAgent, StructuredOutputAgent, SupervisorTeamAgent, SwarmAgent, and AudioAgent.17 min
    24. Prebuilt toolsReference for 10xGraph prebuilt tools: web fetch, file operations, web and semantic search, safe calculator, and long-term memory tools.12 min
    25. TestingTestAgent, QuickTest, TestContext, QuickEval, and mocks for unit tests and evaluations without LLM API calls.9 min
    26. EvaluationThe evaluation API: classes for datasets, criteria, execution and results.17 min
    27. Evaluation criteriaSignatures, parameters, and behaviour of every evaluation criterion class12 min
    28. Evaluation harnessPytest helpers, data models, batch runners and reporters for evaluating 10xGraph agents.14 min

    REST API

    1. Conventions and permissionsThe 10xGraph REST API response envelope, HTTP and WebSocket authentication, the endpoint permission table, WebSocket close codes and HTTP status codes.5 min
    2. Graph endpointsReference for the 10xGraph REST endpoints that invoke, stream, stop, and inspect a graph, with request bodies, responses, and auth requirements.7 min
    3. Live WebSocket endpointReference for WS /v1/graph/live: real-time audio WebSocket bridge for LiveAgent graphs. Init frame, binary and JSON frames, authentication, close codes.8 min
    4. AG-UI endpointPOST /v1/ag-ui runs a 10xGraph graph over the AG-UI protocol: the RunAgentInput request, the server-sent event stream, interrupts, client tools, auth and error codes.6 min
    5. Thread endpointsReference for the 10xGraph REST endpoints that read and write thread state and messages, with request fields, responses, and auth requirements.7 min
    6. Memory store endpointsReference for /v1/store endpoints: storing, searching, listing, updating, deleting, and forgetting memories through the 10xGraph API server.8 min
    7. File upload endpointsReference for the 10xGraph REST endpoints that upload files and retrieve them, with request fields, responses, and authentication requirements.5 min
    8. Configuration endpointsReference for the 10xGraph REST config endpoint GET /v1/config/multimodal: permission, response fields, defaults, errors and a curl example.2 min
    9. Observability endpointsReference for the GET /v1/observability/{thread_id} endpoint that reconstructs a run trace with spans, events, and token usage.5 min
    10. Eval endpointsReference for the eval run listing and detail endpoints that serve 10xgraph eval reports over HTTP, including their public, unauthenticated status.5 min
    11. Health check endpointGET /ping is the unauthenticated health check of the 10xGraph API server, used for Kubernetes probes, Docker HEALTHCHECK and load balancers.2 min

    CLI and configuration

    1. CLI referenceEvery 10xGraph CLI command with its purpose, usage line, options and defaults: init, api, play, dev, build, eval, test, skills, audit, config, demo and version.6 min
    2. 10xgraph.json configuration referenceEvery key the 10xgraph.json config file accepts, with defaults, types, purposes, and complete examples for rate limiting, auth, and servers.6 min
    3. AuthenticationConfigure JWT, custom auth backends, and authorization for the 10xGraph API server.10 min
    4. Rate LimitingComplete reference for the rate_limit block in 10xgraph.json: the backends, limits, and every option for throttling requests to the 10xGraph API server.6 min

    TypeScript client

    1. TenxGraphClientComplete reference for the TenxGraphClient class, constructor config, method list, and exports.10 min
    2. Graph controlReference for graph-control methods on the TypeScript client: ping, graph, graphTools, observability, graphStateSchema, stopGraph, and fixGraph.8 min
    3. MessageReference for the Message class, its factory methods and all 12 content block types in the 10xGraph TypeScript client.11 min
    4. invoke()Reference for TenxGraphClient.invoke(): send messages to the agent graph, run remote tools automatically, and get the final result.6 min
    5. stream()Reference for TenxGraphClient.stream(): send messages and receive StreamChunk objects in real time, with options, event types and examples.6 min
    6. realtime()Reference for TenxGraphClient.realtime() and RealtimeSession, the transport-only audio-to-audio client for the /v1/graph/live WebSocket.9 min
    7. ThreadsReference for listing, inspecting, updating and deleting conversation threads, state and messages with the 10xGraph TypeScript client.6 min
    8. MemoryReference for memory store methods in the 10xGraph TypeScript client: store, search, retrieve, update and delete memories with type-based filtering and vector similarity.7 min
    9. FilesUpload, retrieve, and manage multimodal files with the 10xGraph TypeScript client.5 min
    10. Client authenticationBearer, Basic, and header authentication options for the 10xGraph TypeScript client, with WebSocket auth details.7 min
    11. Error handlingEvery error class exported by the TypeScript client, its status and error code, when it is thrown, and how to handle it.8 min

    Errors

    1. Error Codes ReferenceEvery 10xGraph exception, its error code, whether it is retryable, the HTTP status the API server returns, and how to handle it in code.9 min

    CLI and configuration

    1. Environment VariablesReference for every environment variable the 10xGraph API server recognizes, grouped by area such as auth, CORS, logging, and Snowflake ID settings.10 min