Application Onboarding

Use this guide to add the toolkit to an application or upgrade an existing integration. Keep application agents, tools, and deployment files in your own repository. Use Run your first agent for a local demonstration without model keys.

1. Define the application integration

Decide how the application uses the toolkit:

Application need

Integration

Next guide

Call an existing agent service

Use the HTTP API or AgentClient. The service owns graph execution.

Usage Guide

Serve application agents

Register importable agents through AGENT_PATHS. Run the toolkit API.

Usage Guide

Run graphs inside another application

Own graph execution, authentication, resource lifetime, and concurrency. HTTP service controls do not apply to direct graph calls.

Choose an agent integration and Connections and High Traffic

Choose the smallest agent pattern that meets the requirement. Start with a native tool-calling agent or a fixed graph. Add MCP or Deep Agents when their capabilities are required. See Choose an agent integration for the differences.

2. Install and lock the required dependencies

Select a supported Python version and only the extras that the application uses. Keep the toolkit requirement and the resolved application lockfile in version control. See Installation Options for provider, server, UI, and tool extras. Python 3.14 requires the conditional dependency minimums in that guide.

Choose one of langfuse-v2, langfuse-v3, or langfuse-v4 when the application must retain a specific SDK generation. The SDK selector does not select the server version. Check Langfuse compatibility against the deployed server. Source-checkout dependency groups are not published extras.

For an upgrade, read Migrate authentication and checkpoint storage before changing the application lockfile. Review the resulting changes to LangChain, LangGraph, Pydantic, model SDKs, and observability SDKs together. Preserve the previous lockfile and application image for rollback.

3. Register agents and define resource ownership

Configure AGENT_PATHS with import strings and set DEFAULT_AGENT to a registered agent name. The application module must be installed or copied into the service image. The standard API image contains only the toolkit package. Use the custom-agent example in Usage Guide.

Keep network operations out of agent imports. Use Agent.graph_factory to create concrete models and tools during each service lifespan. The service can then supply its managed connections and configured MCP tools. Keep application-owned clients and stores open until their graphs stop. Close these resources during application shutdown. See Connections and High Traffic and MCP tools.

4. Set identity and memory contracts

For one service deployment per client application, keep the default AUTH_MODE=trusted and one AUTH_SECRET. Keep the shared token in the trusted application backend. user_id is optional. That backend can supply a stable ID for each authenticated user. If it omits the field, the service uses AUTH_SERVICE_USER_ID (default: service). Use a separate database or PostgreSQL schema for each deployment.

For direct access by untrusted users, use AUTH_MODE=token and individual tokens. The service derives identity from the token. See Migrate authentication and checkpoint storage for both modes and token-user feedback requirements.

Keep these identifiers separate:

  • user_id identifies one user across conversations. An agent can use it for a long-term store namespace. The agent must have a store and explicit memory logic. Passing this field alone does not create long-term memory.

  • thread_id identifies one conversation and its short-term checkpoint state. Save the ID returned by the first request. Reuse it for later turns.

  • The agent name selects the graph and forms part of the checkpoint scope. Keep it stable when resuming existing conversations.

  • run_id identifies one execution. Use it for feedback and tracing.

The API scopes checkpoints by user, agent, and public thread ID. Use the same values for invocation, streaming, and history. Configure MEMORY_BACKEND for durability. SQLite supplies checkpoints only. A long-term store is a separate resource. Clearing conversation history does not clear that store.

5. Connect the application client

Use the request and response examples in Usage Guide. Keep one AgentClient open for the application lifetime. Close it during shutdown. For asynchronous applications, use async methods and avoid a synchronous startup request on the event loop.

An asynchronous client must stay in one event loop until aclose() finishes. Streamlit creates a new loop on each asyncio.run(). Close the cached client in a finally block before each page run ends, including st.rerun() and st.stop(). Keep the authenticated user’s identity separate from cached client connections. The included Streamlit page uses this cleanup pattern.

Handle HTTP failures and streaming error events. An SSE stream succeeds only when the application receives a complete result and the completion marker. Close stream iterators when a caller stops reading. Preserve partial text separately from completed answers. Do not automatically retry a run that can have performed a tool action. Use Connections and High Traffic for retry boundaries.

History requests need an explicit thread_id. Follow next_offset when reading paginated history. Token users must retain the returned feedback_token with the corresponding response. Trusted backend feedback keeps its existing request shape. See Migrate authentication and checkpoint storage for the wire changes.

6. Verify the application before production

First, use deterministic models and a disposable database to check the application’s API contract. Then test the real deployment dependencies in a separate environment. The toolkit test suite verifies package behavior; it does not replace tests for application agents, tools, or infrastructure.

Verify these application outcomes:

  • The service becomes ready and lists the expected agents in /info.

  • Invocation, streaming, history, and feedback use the correct user and agent.

  • Two users cannot read each other’s conversations. Two threads for one user have separate histories. Test shared user memories only if a store exists.

  • A restart preserves history and any pending approval that the application supports.

  • Cancellation and concurrent requests release capacity and preserve ordered updates. Failed tools do not cause duplicate external writes.

  • Database interruption and worker failure recover within the deployment’s limits. Overload responses reach the client as errors.

  • The selected model returns valid tool calls and response formats. The configured observability server receives traces and feedback.

Use Testing for test layers, Real LLM verification for a small real-model check, and API load tests for capacity and failure tests. Configure /health/ready for traffic routing and /health/live for supervisor recovery. Tune worker, request, model, and database limits together. See Deployment and Recovery and Connections and High Traffic.

7. Upgrade existing data and release

When upgrading from raw checkpoint IDs to 0.10.x, create the ownership manifest described in Migrate authentication and checkpoint storage. Verify a database backup and the migration dry run before applying changes. Stop all checkpoint writers during migration. Do not run old and new workers against the same checkpoint tables.

Test the migrated conversations through their public IDs and original user identities. Roll out the tested application image and configuration together. Check readiness, error rates, request duration, database capacity, and trace delivery. If data migration must be rolled back, stop writers and restore the verified backup as described in Migrate authentication and checkpoint storage.