Metadata-Version: 2.5
Name: langgraph-agent-toolkit
Version: 0.10.2
Summary: Full toolkit for running an AI agent service built with LangGraph, FastAPI and Streamlit
Project-URL: documentation, https://kryvokhyzha.github.io/langgraph-agent-toolkit
Project-URL: repository, https://github.com/kryvokhyzha/langgraph-agent-toolkit
Project-URL: PyPI, https://pypi.org/project/langgraph-agent-toolkit
Author-email: Roman Kryvokhyzha <kriwohizha@gmail.com>, Joshua Carroll <carroll.joshk@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,blueprint,fastapi,langgraph,litellm,streamlit
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Requires-Dist: certifi>=2026.10.19
Requires-Dist: ddgs>=9.5.0
Requires-Dist: fastapi<0.136.4,>=0.136.3
Requires-Dist: filelock<4,>=3.18
Requires-Dist: fire~=0.7.0
Requires-Dist: httpx~=0.28.1
Requires-Dist: jinja2~=3.1.6
Requires-Dist: joblib>=1.4.2
Requires-Dist: langchain-community<0.4.3,>=0.4.2
Requires-Dist: langchain-core<1.8,>=1.7.0
Requires-Dist: langchain<1.5,>=1.4.7
Requires-Dist: langgraph-checkpoint-postgres<3.3,>=3.2.0
Requires-Dist: langgraph-checkpoint-sqlite<3.2,>=3.1.2
Requires-Dist: langgraph-checkpoint<4.4,>=4.3.1
Requires-Dist: langgraph-prebuilt<1.2,>=1.1.1
Requires-Dist: langgraph-supervisor~=0.0.31
Requires-Dist: langgraph<1.3,>=1.2.18
Requires-Dist: loguru~=0.7.3
Requires-Dist: psycopg[binary,pool]~=3.2.4
Requires-Dist: pydantic-settings<2.14.2,>=2.9.1
Requires-Dist: pydantic<2.13.5,>=2.11.1; python_version < '3.14'
Requires-Dist: pydantic<2.13.5,>=2.13.0; python_version >= '3.14'
Requires-Dist: python-dotenv<1.3,>=1.1
Requires-Dist: rootutils>=1.0.7
Requires-Dist: uvicorn<0.50,>=0.35
Provides-Extra: all
Requires-Dist: arize-phoenix-client<3.6,>=3.5.0; extra == 'all'
Requires-Dist: azure-functions<1.25,>=1.23; extra == 'all'
Requires-Dist: deepagents<0.8,>=0.7.32; extra == 'all'
Requires-Dist: fastmcp<4.2,>=4.1.4; extra == 'all'
Requires-Dist: gunicorn~=26.0.0; extra == 'all'
Requires-Dist: jsonschema-rs>=0.44.1; (python_version >= '3.14') and extra == 'all'
Requires-Dist: langchain-anthropic<1.8,>=1.7.6; extra == 'all'
Requires-Dist: langchain-aws<1.10,>=1.9.1; extra == 'all'
Requires-Dist: langchain-google-genai<4.5,>=4.4.2; extra == 'all'
Requires-Dist: langchain-google-vertexai<3.3,>=3.2.5; extra == 'all'
Requires-Dist: langchain-openai<1.8,>=1.7.3; extra == 'all'
Requires-Dist: langchain[mcp]<1.5,>=1.4.7; extra == 'all'
Requires-Dist: langfuse<6,>=2.60.10; extra == 'all'
Requires-Dist: langgraph-cli[inmem]<0.5.0,>=0.4.40; extra == 'all'
Requires-Dist: langsmith<0.15,>=0.14.14; extra == 'all'
Requires-Dist: mangum~=0.19.0; extra == 'all'
Requires-Dist: openai[aiohttp]<4,>=3.13.0; extra == 'all'
Requires-Dist: openinference-instrumentation-langchain<0.2,>=0.1.80; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.45.1; extra == 'all'
Requires-Dist: opentelemetry-sdk<2,>=1.45.1; extra == 'all'
Requires-Dist: streamlit<1.58.1,>=1.45; extra == 'all'
Requires-Dist: tenacity<10,>=9.1; extra == 'all'
Requires-Dist: uvicorn<0.50,>=0.35; extra == 'all'
Requires-Dist: uvicorn[standard]<0.50,>=0.35; extra == 'all'
Requires-Dist: watchdog~=6.0.0; extra == 'all'
Provides-Extra: all-backends
Requires-Dist: azure-functions<1.25,>=1.23; extra == 'all-backends'
Requires-Dist: gunicorn~=26.0.0; extra == 'all-backends'
Requires-Dist: mangum~=0.19.0; extra == 'all-backends'
Requires-Dist: uvicorn<0.50,>=0.35; extra == 'all-backends'
Requires-Dist: uvicorn[standard]<0.50,>=0.35; extra == 'all-backends'
Provides-Extra: all-llms
Requires-Dist: langchain-anthropic<1.8,>=1.7.6; extra == 'all-llms'
Requires-Dist: langchain-aws<1.10,>=1.9.1; extra == 'all-llms'
Requires-Dist: langchain-google-genai<4.5,>=4.4.2; extra == 'all-llms'
Requires-Dist: langchain-google-vertexai<3.3,>=3.2.5; extra == 'all-llms'
Requires-Dist: langchain-openai<1.8,>=1.7.3; extra == 'all-llms'
Requires-Dist: openai[aiohttp]<4,>=3.13.0; extra == 'all-llms'
Provides-Extra: all-observability
Requires-Dist: arize-phoenix-client<3.6,>=3.5.0; extra == 'all-observability'
Requires-Dist: langfuse<6,>=2.60.10; extra == 'all-observability'
Requires-Dist: langsmith<0.15,>=0.14.14; extra == 'all-observability'
Requires-Dist: openinference-instrumentation-langchain<0.2,>=0.1.80; extra == 'all-observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.45.1; extra == 'all-observability'
Requires-Dist: opentelemetry-sdk<2,>=1.45.1; extra == 'all-observability'
Requires-Dist: tenacity<10,>=9.1; extra == 'all-observability'
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic<1.8,>=1.7.6; extra == 'anthropic'
Provides-Extra: aws
Requires-Dist: langchain-aws<1.10,>=1.9.1; extra == 'aws'
Provides-Extra: aws-backend
Requires-Dist: mangum~=0.19.0; extra == 'aws-backend'
Provides-Extra: azure-backend
Requires-Dist: azure-functions<1.25,>=1.23; extra == 'azure-backend'
Provides-Extra: deepagents
Requires-Dist: deepagents<0.8,>=0.7.32; extra == 'deepagents'
Provides-Extra: google-genai
Requires-Dist: langchain-google-genai<4.5,>=4.4.2; extra == 'google-genai'
Provides-Extra: google-vertexai
Requires-Dist: langchain-google-vertexai<3.3,>=3.2.5; extra == 'google-vertexai'
Provides-Extra: gunicorn-backend
Requires-Dist: gunicorn~=26.0.0; extra == 'gunicorn-backend'
Requires-Dist: uvicorn[standard]<0.50,>=0.35; extra == 'gunicorn-backend'
Provides-Extra: langfuse
Requires-Dist: langfuse<6,>=2.60.10; extra == 'langfuse'
Provides-Extra: langfuse-v2
Requires-Dist: langfuse<3,>=2.60.10; extra == 'langfuse-v2'
Provides-Extra: langfuse-v3
Requires-Dist: langfuse<4,>=3.15.0; extra == 'langfuse-v3'
Provides-Extra: langfuse-v4
Requires-Dist: langfuse<5,>=4.18.0; extra == 'langfuse-v4'
Provides-Extra: langfuse-v5
Requires-Dist: langfuse<6,>=5.0.4; extra == 'langfuse-v5'
Provides-Extra: langsmith
Requires-Dist: langsmith<0.15,>=0.14.14; extra == 'langsmith'
Provides-Extra: mcp
Requires-Dist: fastmcp<4.2,>=4.1.4; extra == 'mcp'
Requires-Dist: langchain[mcp]<1.5,>=1.4.7; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: langchain-openai<1.8,>=1.7.3; extra == 'openai'
Provides-Extra: openai-aiohttp
Requires-Dist: langchain-openai<1.8,>=1.7.3; extra == 'openai-aiohttp'
Requires-Dist: openai[aiohttp]<4,>=3.13.0; extra == 'openai-aiohttp'
Provides-Extra: phoenix
Requires-Dist: arize-phoenix-client<3.6,>=3.5.0; extra == 'phoenix'
Requires-Dist: openinference-instrumentation-langchain<0.2,>=0.1.80; extra == 'phoenix'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.45.1; extra == 'phoenix'
Requires-Dist: opentelemetry-sdk<2,>=1.45.1; extra == 'phoenix'
Requires-Dist: tenacity<10,>=9.1; extra == 'phoenix'
Provides-Extra: studio
Requires-Dist: jsonschema-rs>=0.44.1; (python_version >= '3.14') and extra == 'studio'
Requires-Dist: langgraph-cli[inmem]<0.5.0,>=0.4.40; extra == 'studio'
Provides-Extra: ui
Requires-Dist: streamlit<1.58.1,>=1.45; extra == 'ui'
Requires-Dist: watchdog~=6.0.0; extra == 'ui'
Provides-Extra: uvicorn-backend
Requires-Dist: uvicorn<0.50,>=0.35; extra == 'uvicorn-backend'
Description-Content-Type: text/markdown

<div align="center">
  <img alt="LangGraph Agent Toolkit" src="https://raw.githubusercontent.com/kryvokhyzha/langgraph-agent-toolkit/main/docs/media/logo.svg" width="260">
</div>

# LangGraph Agent Toolkit

[![Tests](https://github.com/kryvokhyzha/langgraph-agent-toolkit/actions/workflows/test.yml/badge.svg)](https://github.com/kryvokhyzha/langgraph-agent-toolkit/actions/workflows/test.yml)
[![Documentation](https://github.com/kryvokhyzha/langgraph-agent-toolkit/actions/workflows/sphinx.yml/badge.svg)](https://github.com/kryvokhyzha/langgraph-agent-toolkit/actions/workflows/sphinx.yml)
[![PyPI](https://img.shields.io/pypi/v/langgraph-agent-toolkit.svg)](https://pypi.org/project/langgraph-agent-toolkit/)

Serve LangGraph agents through an authenticated HTTP API. Add streaming,
persistent conversation history, managed model connections, and optional tools
and observability. Use your own client or the included Streamlit interface.

**Python 3.11–3.14.** The API image uses Python 3.13. Existing deployments
should read the [migration guide for the current release](docs/migration.rst)
and [changelog](CHANGELOG.md) before upgrading.

[Quickstart](#quickstart) · [Integrations](#choose-an-integration) ·
[Onboarding](docs/onboarding.rst) ·
[Memory and authentication](#memory-and-authentication) ·
[Deployment](#deployment) · [Documentation](#documentation) ·
[Development](#development)

## What the toolkit provides

- FastAPI routes for invocation, SSE, JSON Lines, conversation lists, history,
  and feedback.
- Sync and async `AgentClient` interfaces, including multimodal messages.
- SQLite or PostgreSQL checkpoints with conversation ownership and ordered
  updates across workers.
- Model factories with connection reuse, timeouts, bounded retries, and an
  optional aiohttp transport for OpenAI and Azure.
- Native LangChain agents, custom LangGraph workflows, human approvals, and
  optional Deep Agents.
- Optional tool selection for native agents and Deep Agents. Keep the full
  catalog by default. Use LLM selection or supported provider tool search.
- MCP tools, Langfuse SDK v2/v3/v4/v5 integration, LangSmith, Phoenix, and local
  or managed prompts.

Install only the integrations that your service needs. LiteLLM, Langfuse,
Phoenix, MCP, Deep Agents, and Streamlit are optional.

## Quickstart

This local demo uses a deterministic fake model and SQLite. It needs no model
key, Docker, or external service. It checks API behavior and persistence. Model
quality requires separate evaluation.

Install `uv` 0.13.6 or later, then use a fresh checkout:

```sh
git clone https://github.com/kryvokhyzha/langgraph-agent-toolkit.git
cd langgraph-agent-toolkit
uv sync --frozen --no-install-project --no-dev --extra uvicorn-backend
```

Create `.env` in this fresh checkout with these values. Use a shell without
other toolkit or tracing overrides.

```dotenv
USE_FAKE_MODEL=true
AUTH_MODE=trusted
AUTH_SECRET=local-demo-token
AGENT_PATHS=["langgraph_agent_toolkit.agents.blueprints.chatbot.agent:chatbot_agent"]
DEFAULT_AGENT=chatbot-agent
MEMORY_BACKEND=sqlite
SQLITE_DB_PATH=quickstart.sqlite
OBSERVABILITY_BACKEND=empty
MCP_SERVERS={}
MODEL_CONFIGS={}
LANGSMITH_TRACING=false
LANGCHAIN_TRACING_V2=false
```

Start the API on localhost:

```sh
uv run --no-sync python -m langgraph_agent_toolkit.run_api --host 127.0.0.1 --port 8080
```

In another terminal, check readiness and send a request:

```sh
export AUTH_SECRET=local-demo-token

curl --fail http://127.0.0.1:8080/health/ready

curl --fail-with-body http://127.0.0.1:8080/chatbot-agent/invoke \
  -H "Authorization: Bearer ${AUTH_SECRET}" \
  -H 'Content-Type: application/json' \
  -d '{"input":{"message":"Hello"},"user_id":"demo-user","thread_id":"demo-thread"}'
```

The response content is `This is a test response from the fake model.` Reuse the
same `user_id` and `thread_id` for the next turn. The SQLite file retains
history after the API stops. Use the demo token only for this local example.

Use the [quickstart guide](docs/quickstart.rst) for streaming, saved history,
the Python client, the UI, and real-model configuration.

## Choose an integration

| Need                                         | Start with                                          | Guide                                                                       |
| -------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
| Chat without tools                           | `chatbot`                                           | [Agent patterns](docs/integrations.rst)                                     |
| A model that selects business tools          | Native `create_agent`                               | [Usage](docs/usage.rst)                                                     |
| Structured extraction                        | `create_agent_structured`                           | [Agent patterns](docs/integrations.rst)                                     |
| A fixed workflow or required approval        | Custom `StateGraph` or human-in-the-loop middleware | [Usage](docs/usage.rst)                                                     |
| Planning, intermediate files, and delegation | Optional Deep Agents                                | [Deep Agents](docs/deepagents.rst)                                          |
| Tools exposed by another service             | MCP, combined with a supported agent                | [MCP](docs/mcp.rst)                                                         |
| Large tool catalogs                          | Optional LangChain tool selection                   | [Tool selection](docs/tool_selection.rst)                                   |
| Traces, prompts, and feedback                | Langfuse, LangSmith, or Phoenix                     | [Observability choices](docs/integrations.rst), [Phoenix](docs/phoenix.rst) |

For an existing Python project, select provider and backend extras:

```sh
uv add 'langgraph-agent-toolkit[openai,uvicorn-backend,langfuse-v5]'
```

Follow the [application onboarding guide](docs/onboarding.rst) to register
agents, set identity and memory contracts, connect a client, and verify the
deployment. It also gives the upgrade sequence for existing applications.

`langfuse-v2`, `langfuse-v3`, `langfuse-v4`, and `langfuse-v5` select a Python
SDK version range. Choose one. SDK and server versions are separate. SDK v5
requires server 4.59.0 or later. Keep `langfuse-v4` or `langfuse-v3` for server
v3. Use the compatibility guide for supported combinations. `mcp`, `deepagents`,
`ui`, and `openai-aiohttp` are separate extras. See
[installation](docs/installation.rst) for all options.

## Memory and authentication

`thread_id` identifies short-term conversation state. A long-term store can use
`user_id` to identify one user across threads. Passing `user_id` does not create
a store. SQLite supplies checkpoints but has no long-term store.

The service separates conversation storage by authenticated user, agent, and
public thread ID. Keep these values consistent when reading or updating history.

Use `/threads` to list saved conversations for one user and agent. Use
`/history` to read messages in one conversation. History returns at most 100
messages by default. Follow `next_offset` for more messages and `next_cursor`
for more conversations. See the [usage guide](docs/usage.rst) for examples and
storage limits.

For one deployment per client, keep one `AUTH_SECRET`. The default
`AUTH_MODE=trusted` preserves 0.9.2 shared bearer-token authentication.
`user_id` is optional. Your trusted application can supply an end user's ID. If
it omits the field, the service uses `AUTH_SERVICE_USER_ID` (default:
`service`). Keep that identity stable for each conversation.

No new auth header or per-user token is required. If an existing deployment sets
`AUTH_MODE=token`, remove that override or set it to `trusted` to use the
compatible behavior. Token mode remains available as an explicit option.
`AUTH_USERS` tokens always identify one user, in either mode. The service
rejects a different supplied user ID for those tokens.

Authentication compatibility does not remove the history pagination, checkpoint
migration, or validation changes. See the
[authentication and migration guide](docs/migration.rst) for curl examples and
existing checkpoint migration.

## Deployment

The API can run alone under Uvicorn or Gunicorn. Docker Compose adds the
optional frontend, model proxy, and observability services. Configure the full
stack through the [environment guide](docs/environment_setup.rst).

- Both Docker images use separate build and runtime stages, a slim Python base,
  and locked production dependencies. See the
  [image build and measurement guide](docs/deployment.rst#production-image-builds).
- The API Docker image installs and selects **aiohttp** for managed async OpenAI
  and Azure calls. Python installations default to HTTPX. Set
  `LLM_HTTP_ASYNC_TRANSPORT=httpx` to override the image default.
- Each worker accepts eight active requests by default. Excess work receives
  `503` before an agent run starts. The optional admission queue is bounded.
- Use PostgreSQL for replicas across hosts. SQLite workers must share a file on
  a local filesystem. Configure persistence; the default backend is unset.
- Supervisors replace failed workers. Requests running in a failed worker can
  fail. The toolkit does not provide durable jobs or exactly-once tool writes.

Read [deployment](docs/deployment.rst) for health probes and worker recovery,
and [reliability](docs/reliability.rst) for database pools, connection limits,
timeouts, cancellation, and retry boundaries.

## Documentation

Read the
[documentation site](https://kryvokhyzha.github.io/langgraph-agent-toolkit/) or
the source guides below. The running service exposes its HTTP schema at `/docs`
and `/openapi.json`.

| Task                                 | Guide                                                                                                                                                            |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Make the first request               | [Quickstart](docs/quickstart.rst)                                                                                                                                |
| Add the toolkit to an application    | [Onboarding](docs/onboarding.rst)                                                                                                                                |
| Select extras and configure services | [Installation](docs/installation.rst), [environment](docs/environment_setup.rst)                                                                                 |
| Call the API or register an agent    | [Usage](docs/usage.rst)                                                                                                                                          |
| Choose agents and tools              | [Integrations](docs/integrations.rst), [MCP](docs/mcp.rst), [Deep Agents](docs/deepagents.rst)                                                                   |
| Upgrade an existing deployment       | [Migration](docs/migration.rst), [dependency review](docs/dependency_updates.rst), [changelog](CHANGELOG.md)                                                     |
| Deploy and operate the service       | [Deployment](docs/deployment.rst), [reliability](docs/reliability.rst)                                                                                           |
| Configure Langfuse                   | [SDK and server compatibility](docs/langfuse_compatibility.rst)                                                                                                  |
| Configure Phoenix                    | [Phoenix tracing, prompts, and feedback](docs/phoenix.rst)                                                                                                       |
| Verify behavior and capacity         | [Testing](docs/testing.rst), [live model checks](docs/live_llm_testing.rst), [load tests](docs/load_testing.rst), [recorded results](docs/load_test_results.rst) |

## Development

Install the locked dependencies and run the local tests. The pre-commit hook
environments require Python 3.13.

```sh
uv sync --frozen --no-install-project --extra all
uv run --no-sync pytest
uv run --no-sync pre-commit run --all-files
```

Use `--extra all` because `--all-extras` selects incompatible Langfuse SDK
versions. Ordinary tests use fake models and local services. Process, Docker,
PostgreSQL, live Langfuse, and real-model checks have separate setup
requirements. Test coverage and local load results do not establish production
capacity or model quality.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Examples
are in [scripts/python](scripts/python), including the
[Deep Agents example](scripts/python/10-deep-agent.py).

## License

[MIT](LICENSE).
