Langroid
A Python framework for orchestrating LLM agents, tools, and retrieval workflows through explicit tasks.
- Source repo
- langroid/langroid
- Stars
- ★ 4.1k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 70/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code · OpenAI APIClaude API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Python team building a teacher-and-student workflow can create ChatAgents, wrap them in Tasks, and connect the student tasks with add_sub_task().
- Not a fit if
- Users who want a ready-made chat UI without writing Python
- Projects pinned to Python 3.10 or earlier
- Source review
- 70/100 · Some gaps
What does this agent do, and when should you use it?
Langroid is a Python framework for LLM applications built around the Agent and Task abstractions. An Agent can hold conversation state and optionally use an LLM, vector store, and tools or functions, while a Task iterates responders and delegates recursively to hierarchical subtasks. It supports OpenAI models and documented local or remote model paths through proxy libraries and compatible model servers, alongside structured output, async methods, logging, and message lineage. Specialized agents cover document RAG, SQL, Neo4j, and tabular data, making it a fit for teams that want to express multi-agent workflows directly in Python.
Developers create a ChatAgent or another Agent, configure its model through ChatAgentConfig, and call llm_response() for stateful model interaction. Wrapping an agent in Task enables Task.run() to iterate among LLM, Agent, and User responders; add_sub_task() adds subordinate tasks to a multi-agent loop. A developer defines a Pydantic-backed ToolMessage, enables it with enable_message(), and implements an agent handler that accepts the tool message and returns a result; Langroid supports both OpenAI function calling and its native tool mechanism. DocChatAgent reads local paths or URLs, shards and embeds documents, stores them in a vector database, and performs retrieval-augmented question answering; its MCP tool adapter converts MCP Server tools into ToolMessage instances.
- A Python team building a teacher-and-student workflow can create ChatAgents, wrap them in Tasks, and connect the student tasks with add_sub_task().
- A legal-operations application extracting nested lease terms can combine a retrieval-backed DocChatAgent with a ToolMessage-based extraction agent that emits structured information.
- A research or support team with PDFs, URLs, or local text can use DocChatAgentConfig.doc_paths to create a cited, vector-retrieval question-answering workflow.
- An analyst querying a CSV, URL, or Pandas DataFrame can use TableChatAgent, whose LLM generates Pandas code that the agent executes through its tool/function mechanism.
- A developer who needs an LLM agent to use existing MCP Server tools can use the documented MCP adapter to expose those tools as ToolMessage instances.
How do you install or deploy this agent?
Langroid requires Python 3.11+. In an activated virtual environment, install the core package with:
pip install langroidFor HuggingFace sentence-transformers embeddings:
pip install "langroid[hf-embeddings]"Install langroid[doc-chat] for document parsers and langroid[db] for database chat. The simplest OpenAI setup requires OPENAI_API_KEY: copy .env-template to .env and set it, or export the variable in the shell.
How do you use this agent?
A minimal task invocation is:
import langroid as lr
agent = lr.ChatAgent()
task = lr.Task(agent, name="Bot")
task.run("Hello")For an explicit OpenAI model configuration:
import langroid.language_models as lm
mdl = lm.OpenAIGPT(lm.OpenAIGPTConfig(chat_model=lm.OpenAIChatModel.GPT4o))
response = mdl.chat("What is the capital of Ontario?", max_tokens=10)For a local or OpenAI-compatible endpoint, set chat_model to a documented value such as "ollama/mistral" or "local/localhost:8000".
What are this agent's strengths and limitations?
- Agent and Task are first-class abstractions: Task.run() shares a responder-style signature that lets subtasks participate as additional responders in recursive orchestration.
- Pydantic-backed tool definitions provide one developer-facing interface for both OpenAI function calling and Langroid ToolMessage tools, including feedback for malformed model JSON.
- DocChatAgent provides an end-to-end RAG path from local paths or URLs through sharding, embedding, vector storage, and question answering; the README lists several supported vector stores.
- The repository documents an MCP tool adapter, async methods, message lineage, and self-contained HTML task logs for execution and observability.
- The runtime requirement is Python 3.11+, and document parsing plus most vector database support are optional extras that must be selected for the intended deployment.
- The simplest setup uses an OpenAI API key; Redis, Qdrant, Google Search, and Momento features require their own services or credentials.
- The README says its prompts and instructions have been tested mainly with GPT-4 and to some extent GPT-4o; other local or commercial models may require prompt or workflow changes and can produce weaker results.
- Using SQL chat with PostgreSQL requires platform PostgreSQL development libraries and the postgres extra; installing the all extra increases installation size and startup time.
How does this agent compare with similar options?
Langroid states that it does not use LangChain or another LLM framework; instead, it presents Agent, Task, and message passing as its programming model for multi-agent applications. It also documents model access through LiteLLM and local model servers rather than limiting use to OpenAI.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Langroid This agent | 70 · Some gaps | Library / SDKFree + model costs | ★ 4.1k | today | Python | Claude Code · OpenAI API |
| BeeAI Framework | 51 · Major gaps | Library / SDKFree + model costs | ★ 3.5k | 3d ago | Python | — |
| Swarm (Experimental, Educational) | 51 · Major gaps | Library / SDKFree + model costs | ★ 22k | 6mo ago | Python | OpenAI API |
| LLM Tornado for .NET | 50 · Major gaps | Library / SDKFree + model costs | ★ 651 | today | C# | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: SECURITY.md clearly defines threat model, noting code execution is a feature, and recommends least-privilege DB roles, container isolation. pyproject.toml has version ranges for dependencies but no vulnerability scan evidence. User confirmation exists (e.g., allow_dangerous_operations flag) but not universal. Data flow transparency: docs explain tool execution but not detailed data flow. Sensitive data handling: recommends container isolation but no concrete implementation. External effects: tools can execute code, but docs warn. Rollback: RewindTool exists but not detailed. Source attribution: author info clear. Deductions: user confirmation not default, data flow transparency insufficient, rollback limited.
Evidence: README and SECURITY.md consistent, no contradictions. Dependencies have version ranges but no availability guarantee. Failure messages: test config has retry mechanism but no specific error message examples. Deductions: dependency availability unverified, failure messages not detailed.
Evidence: README describes multiple scenarios (RAG, SQL, multi-agent), audience is developers. Capability boundaries: SECURITY.md clearly defines code execution boundaries. Trigger precision: tool invocation has clear mechanisms. Environment fit: supports multiple LLMs and databases. Deductions: capability boundaries documented but not all scenarios covered.
Evidence: README well-structured with doc links. Install notes: pyproject.toml has dependencies and extras. Naming stability: version numbers clear. Examples: README has code examples. Known limitations: SECURITY.md has threat model. License: MIT. Versioning: README has changelog. Maintenance responsibility: author info clear. Deductions: install notes lack detailed steps.
Evidence: Output usability: structured output support. Marginal value: multi-agent framework has unique value. Cost-benefit: many dependencies but optional installs. Deductions: cost-benefit not quantified.
Evidence: README has citations (e.g., Nullify quote) but no verification method. Cross-source: external blog references. Fact-inference separation: SECURITY.md distinguishes security boundaries. Deductions: citations unverified, cross-source limited.
- Code execution is a feature; strict privilege and sandboxing required.
- Many dependencies; regular vulnerability checks needed.
- User confirmation not default; configure as needed.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Three fixes, each one a case where langroid did something worse than fail: an unrecoverable crash on an ordinary model mistake, and a cleanup helper that deleted data it was supposed to leave alone. Agents **Parallel tool-calls no longer crash the task when one has bad arguments** (#1282, fixes #1280 reported by @swf1996120). OpenAI returns several tool-calls per turn by default. If one of them failed ToolMessage validation, langroid returned a single error string for the whole batch and Agent.process_tool_results tripped …View on GitHub ↗ -
Release notes excerpt
Parsing / RAG robustness **Out-of-range segment specs no longer blow up memory ([#1287](https://github.com/langroid/langroid/pull/1287), fixes [#1286](https://github.com/langroid/langroid/issues/1286))** extract_numbered_segments used to resolve its segment spec through parse_number_range_list, which materializes every number in every range into a set. A segment spec is *model output*, so it is not bounded by what the passage actually contains: a weak model — or one echoing a number out of a retrieved document — can emit a perfectly well-formed range reaching far past …View on GitHub ↗ -
Release notes excerpt
Full Changelog: https://github.com/langroid/langroid/compare/0.69.18...0.69.19View on GitHub ↗