langroid Agent工作流

⚙️ Installation and Setup

Install `langroid`

Langroid requires Python 3.11+. We recommend using a virtual environment. Use pip to install a bare-bones slim version of langroid (from PyPi) to your virtual environment:

pip install langroid

pip install "langroid[hf-embeddings]"

    pip install "langroid[doc-chat]"
    

    pip install "langroid[db]"
    

    pip install "langroid[doc-chat,db]"
    

    pip install "langroid[all]"
    

If you are using SQLChatAgent (e.g. the script examples/data-qa/sql-chat/sql_chat.py), with a postgres db, you will need to:

- Install PostgreSQL dev libraries for your platform, e.g. - sudo apt-get install libpq-dev on Ubuntu, - brew install postgresql on Mac, etc. - Install langroid with the postgres extra, e.g. pip install langroid[postgres] or poetry add "langroid[postgres]" or poetry install -E postgres, (or the corresponding uv versions, e.g. uv add "langroid[postgres]" or uv pip install langroid[postgres]). If this gives you an error, try pip install psycopg2-binary in your virtualenv. </details>

📝 If you get strange errors involving mysqlclient, try doing pip uninstall mysqlclient followed by pip install mysqlclient.

🐳 Docker Instructions

We provide a containerized version of the langroid-examples repository via this Docker Image. All you need to do is set up environment variables in the .env file. Please follow these steps to setup the container:

```bash

Use this command to run any of the scripts in the `examples` directory

python examples/<Path/To/Example.py> ```

🎉 Usage Examples

These are quick teasers to give a glimpse of what you can do with Langroid and how your code would look.

⚠️ The code snippets below are intended to give a flavor of the code and they are not complete runnable examples! For that we encourage you to consult the langroid-examples repository.

ℹ️ The various LLM prompts and instructions in Langroid have been tested to work well with GPT-4 (and to some extent GPT-4o). Switching to other LLMs (local/open and proprietary) is easy (see guides mentioned above), and may suffice for some applications, but in general you may see inferior results unless you adjust the prompts and/or the multi-agent setup.

📖 Also see the Getting Started Guide for a detailed tutorial.

Click to expand any of the code examples below. All of these can be run in a Colab notebook:

<details> <summary> <b> Direct interaction with LLM </b> </summary>

import langroid.language_models as lm

mdl = lm.OpenAIGPT(
    lm.OpenAIGPTConfig(
        chat_model=lm.OpenAIChatModel.GPT4o, # or, e.g.  "ollama/qwen2.5"
    ),
)

messages = [
  lm.LLMMessage(content="You are a helpful assistant",  role=lm.Role.SYSTEM), 
  lm.LLMMessage(content="What is the capital of Ontario?",  role=lm.Role.USER),
]

response = mdl.chat(messages, max_tokens=200)
print(response.message)

<details> <summary> <b> Interaction with non-OpenAI LLM (local or remote) </b> </summary> Local model: if model is served at http://localhost:8000:

```python cfg = lm.OpenAIGPTConfig( chat_model="local/localhost:8000", chat_context_length=4096 ) mdl = lm.OpenAIGPT(cfg)

🚀 Demo

Suppose you want to extract structured information about the key terms of a commercial lease document. You can easily do this with Langroid using a two-agent system, as we show in the langroid-examples repo. (See this script for a version with the same functionality using a local Mistral-7b model.) The demo showcases just a few of the many features of Langroid, such as: - Multi-agent collaboration: LeaseExtractor is in charge of the task, and its LLM (GPT4) generates questions to be answered by the DocAgent. - Retrieval augmented question-answering, with source-citation: DocAgent LLM (GPT4) uses retrieval from a vector-store to answer the LeaseExtractor's questions, cites the specific excerpt supporting the answer. - Function-calling (also known as tool/plugin): When it has all the information it needs, the LeaseExtractor LLM presents the information in a structured format using a Function-call.

Here is what it looks like in action (a pausable mp4 video is here).

Claude Code Plugin (Optional)

This plugin provides two skills:

- langroid:patterns - Your Claude Code agent can leverage this skill to produce Langroid multi-agent code using proper design patterns. - langroid:add-pattern - The agent can use this skill to record new patterns it learns, for future reference, either autonomously or when prompted by the user.

Step 1: Add the Langroid marketplace

From terminal:

claude plugin marketplace add langroid/langroid

Or within Claude Code:

/plugin marketplace add langroid/langroid

Step 2: Install the Langroid plugin

From terminal:

claude plugin install langroid@langroid

Or within Claude Code:

/plugin install langroid@langroid

Once installed, simply ask your Claude Code agent to implement Langroid patterns in natural language, e.g.,

set up a Langroid agent so it uses the EditTool, and wrap it in a task that ends as soon as the tool is generated

and it will automatically use the langroid:patterns skill to follow the right design pattern.

You can also ask Claude Code to record a new pattern when you discover one, e.g.,

record this as a new Langroid pattern for setting up MCP tools

Set up environment variables (API keys, etc)

To get started, all you need is an OpenAI API Key. If you don't have one, see this OpenAI Page. (Note that while this is the simplest way to get started, Langroid works with practically any LLM, not just those from OpenAI. See the guides to using Open/Local LLMs, and other non-OpenAI proprietary LLMs.)

In the root of the repo, copy the .env-template file to a new file .env:

cp .env-template .env

OPENAI_API_KEY=your-key-here-without-quotes
OPENAI_ORGANIZATION=optionally-your-organization-id

Alternatively, you can set this as an environment variable in your shell (you will need to do this every time you open a new shell):

export OPENAI_API_KEY=your-key-here-without-quotes

<details> <summary><b>Optional Setup Instructions (click to expand) </b></summary>

All of the following environment variable settings are optional, and some are only needed to use specific features (as noted below).

- Qdrant Vector Store API Key, URL. This is only required if you want to use Qdrant cloud. Alternatively Chroma or LanceDB are also currently supported. We use the local-storage version of Chroma, so there is no need for an API key. - Redis Password, host, port: This is optional, and only needed to cache LLM API responses using Redis Cloud. Redis offers a free 30MB Redis account which is more than sufficient to try out Langroid and even beyond. If you don't set up these, Langroid will use a pure-python Redis in-memory cache via the Fakeredis library. - Momento Serverless Caching of LLM API responses (as an alternative to Redis). To use Momento instead of Redis: - enter your Momento Token in the .env file, as the value of MOMENTO_AUTH_TOKEN (see example file below), - in the .env file set CACHE_TYPE=momento (instead of CACHE_TYPE=redis which is the default). - GitHub Personal Access Token (required for apps that need to analyze git repos; token-based API calls are less rate-limited). See this GitHub page. - Google Custom Search API Credentials: Only needed to enable an Agent to use the GoogleSearchTool. To use Google Search as an LLM Tool/Plugin/function-call, you'll need to set up a Google API key, then setup a Google Custom Search Engine (CSE) and get the CSE ID. (Documentation for these can be challenging, we suggest asking GPT4 for a step-by-step guide.) After obtaining these credentials, store them as values of GOOGLE_API_KEY and GOOGLE_CSE_ID in your .env file. Full documentation on using this (and other such "stateless" tools) is coming soon, but in the meantime take a peek at this chat example, which shows how you can easily equip an Agent with a GoogleSearchtool.

If you add all of these optional variables, your .env file should look like this:

OPENAI_API_KEY=your-key-here-without-quotes
GITHUB_ACCESS_TOKEN=your-personal-access-token-no-quotes
CACHE_TYPE=redis # or momento
REDIS_PASSWORD=your-redis-password-no-quotes
REDIS_HOST=your-redis-hostname-no-quotes
REDIS_PORT=your-redis-port-no-quotes
MOMENTO_AUTH_TOKEN=your-momento-token-no-quotes # instead of REDIS* variables
QDRANT_API_KEY=your-key
QDRANT_API_URL=https://your.url.here:6333 # note port number must be included
GOOGLE_API_KEY=your-key
GOOGLE_CSE_ID=your-cse-id

<details> <summary><b>Optional setup instructions for Microsoft Azure OpenAI(click to expand)</b></summary>

When using Azure OpenAI, additional environment variables are required in the .env file. This page Microsoft Azure OpenAI provides more information, and you can set each environment variable as follows:

- AZURE_OPENAI_API_KEY, from the value of API_KEY - AZURE_OPENAI_API_BASE from the value of ENDPOINT, typically looks like https://your.domain.azure.com. - For AZURE_OPENAI_API_VERSION, you can use the default value in .env-template, and latest version can be found here - AZURE_OPENAI_DEPLOYMENT_NAME is the name of the deployed model, which is defined by the user during the model setup - AZURE_OPENAI_MODEL_NAME Azure OpenAI allows specific model names when you select the model for your deployment. You need to put precisly the exact model name that was selected. For example, GPT-4 (should be gpt-4-32k or gpt-4). - AZURE_OPENAI_MODEL_VERSION is required if AZURE_OPENAI_MODEL_NAME = gpt=4, which will assist Langroid to determine the cost of the model </details>

---

get the .env file template from `langroid` repo

wget -O .env https://raw.githubusercontent.com/langroid/langroid/main/.env-template

Edit the .env file with your favorite editor (here nano), and remove any un-used settings. E.g. there are "dummy" values like "your-redis-port" etc -- if you are not using them, you MUST remove them.

nano .env

answer = agent.llm_response("What is the capital of Ontario?")

# ... OR instead, set up a task (which has a built-in loop) and run it task = lr.Task(agent, name="Bot") task.run() # ... a loop seeking response from LLM or User at each turn

</details>

<details>
<summary><b> Three communicating agents </b></summary>

A toy numbers game, where when given a number `n`:
- `repeater_task`'s LLM simply returns `n`,
- `even_task`'s LLM returns `n/2` if `n` is even, else says "DO-NOT-KNOW"
- `odd_task`'s LLM returns `3*n+1` if `n` is odd, else says "DO-NOT-KNOW"

Each of these `Task`s automatically configures a default `ChatAgent`.

repeater_task = lr.Task( name = "Repeater", system_message=""" Your job is to repeat whatever number you receive. """, llm_delegate=True, # LLM takes charge of task single_round=False, )

even_task = lr.Task( name = "EvenHandler", system_message=f""" You will be given a number. If it is even, divide by 2 and say the result, nothing else. If it is odd, say {NO_ANSWER} """, single_round=True, # task done after 1 step() with valid response )

odd_task = lr.Task( name = "OddHandler", system_message=f""" You will be given a number n. If it is odd, return (n*3+1), say nothing else. If it is even, say {NO_ANSWER} """, single_round=True, # task done after 1 step() with valid response )

Then add the `even_task` and `odd_task` as sub-tasks of `repeater_task`, 
and run the `repeater_task`, kicking it off with a number as input:

</details>

<details>
<summary><b> Simple Tool/Function-calling example </b></summary>

Langroid leverages Pydantic to support OpenAI's
[Function-calling API](https://platform.openai.com/docs/guides/gpt/function-calling)
as well as its own native tools. The benefits are that you don't have to write
any JSON to specify the schema, and also if the LLM hallucinates a malformed
tool syntax, Langroid sends the Pydantic validation error (suitably sanitized) 
to the LLM so it can fix it!

Simple example: Say the agent has a secret list of numbers, 
and we want the LLM to find the smallest number in the list. 
We want to give the LLM a `probe` tool/function which takes a
single number `n` as argument. The tool handler method in the agent
returns how many numbers in its list are at most `n`.

First define the tool using Langroid's `ToolMessage` class:

class ProbeTool(lr.agent.ToolMessage): request: str = "probe" # specifies which agent method handles this tool purpose: str = """ To find how many numbers in my list are less than or equal to the <number> you specify. """ # description used to instruct the LLM on when/how to use the tool number: int # required argument to the tool

Then define a `SpyGameAgent` as a subclass of `ChatAgent`, 
with a method `probe` that handles this tool:

def probe(self, msg: ProbeTool) -> str: # return how many numbers in self.numbers are less or equal to msg.number return str(len([n for n in self.numbers if n <= msg.number]))

We then instantiate the agent and enable it to use and respond to the tool:

For a full working example see the
[chat-agent-tool.py](https://github.com/langroid/langroid-examples/blob/main/examples/quick-start/chat-agent-tool.py)
script in the `langroid-examples` repo.
</details>

<details>
<summary> <b>Tool/Function-calling to extract structured information from text </b> </summary>

Suppose you want an agent to extract 
the key terms of a lease, from a lease document, as a nested JSON structure.
First define the desired structure via Pydantic models:

class LeaseFinancials(BaseModel): monthly_rent: str deposit: str

class Lease(BaseModel): period: LeasePeriod financials: LeaseFinancials address: str

Then define the `LeaseMessage` tool as a subclass of Langroid's `ToolMessage`.
Note the tool has a required argument `terms` of type `Lease`:

class LeaseMessage(lr.agent.ToolMessage): request: str = "lease_info" purpose: str = """ Collect information about a Commercial Lease. """ terms: Lease

Then define a `LeaseExtractorAgent` with a method `lease_info` that handles this tool,
instantiate the agent, and enable it to use and respond to this tool:

See the [`chat_multi_extract.py`](https://github.com/langroid/langroid-examples/blob/main/examples/docqa/chat_multi_extract.py)
script in the `langroid-examples` repo for a full working example.
</details>

<details>
<summary><b> Chat with documents (file paths, URLs, etc) </b></summary>

Langroid provides a specialized agent class `DocChatAgent` for this purpose.
It incorporates document sharding, embedding, storage in a vector-DB, 
and retrieval-augmented query-answer generation.
Using this class to chat with a collection of documents is easy.
First create a `DocChatAgentConfig` instance, with a 
`doc_paths` field that specifies the documents to chat with.

config = DocChatAgentConfig( doc_paths = [ "https://en.wikipedia.org/wiki/Language_model", "https://en.wikipedia.org/wiki/N-gram_language_model", "/path/to/my/notes-on-language-models.txt", ], vecdb=lr.vector_store.QdrantDBConfig(), )

Then instantiate the `DocChatAgent` (this ingests the docs into the vector-store):

Then we can either ask the agent one-off questions,

or wrap it in a `Task` and run an interactive loop with the user:

See full working scripts in the 
[`docqa`](https://github.com/langroid/langroid-examples/tree/main/examples/docqa)
folder of the `langroid-examples` repo.
</details>

<details>
<summary><b> 🔥 Chat with tabular data (file paths, URLs, dataframes) </b></summary>

Using Langroid you can set up a `TableChatAgent` with a dataset (file path, URL or dataframe),
and query it. The Agent's LLM generates Pandas code to answer the query, 
via function-calling (or tool/plugin), and the Agent's function-handling method
executes the code and returns the answer.

Here is how you can do this:

Set up a `TableChatAgent` for a data file, URL or dataframe
(Ensure the data table has a header row; the delimiter/separator is auto-detected):

2-Agent chat loop: Teacher Agent asks questions to Student Agent

teacher_agent = lr.ChatAgent(agent_cfg) teacher_task = lr.Task( teacher_agent, name="Teacher", system_message=""" Ask your student concise numbers questions, and give feedback. Start with a question. """ ) student_agent = lr.ChatAgent(agent_cfg) student_task = lr.Task( student_agent, name="Student", system_message="Concisely answer the teacher's questions.", single_round=True, )

teacher_task.add_sub_task(student_task) teacher_task.run() ```