Skip to content

The agent engineering platform.

core[patch]: Document agent schema (#23194)

Eugene Yurtsev1fcf875fe329
diff --git a/libs/core/langchain_core/agents.py b/libs/core/langchain_core/agents.py
index 105587ae8d..cfe0396dac 100644
--- a/libs/core/langchain_core/agents.py
+++ b/libs/core/langchain_core/agents.py
@@ -1,32 +1,25 @@
-"""
-**Agent** is a class that uses an LLM to choose a sequence of actions to take.
+"""Schema definitions for representing agent actions, observations, and return values.
-In Chains, a sequence of actions is hardcoded. In Agents,
-a language model is used as a reasoning engine to determine which actions
-to take and in which order.
+**ATTENTION** The schema definitions are provided for backwards compatibility.
-Agents select and use **Tools** and **Toolkits** for actions.
+ New agents should be built using the langgraph library
+ (https://github.com/langchain-ai/langgraph)), which provides a simpler
+ and more flexible way to define agents.
+
+ Please see the migration guide for information on how to migrate existing
+ agents to modern langgraph agents:
+ https://python.langchain.com/v0.2/docs/how_to/migrate_agent/
-**Class hierarchy:**
+Agents use language models to choose a sequence of actions to take.
-.. code-block::
+A basic agent works in the following manner:
- BaseSingleActionAgent --> LLMSingleActionAgent
- OpenAIFunctionsAgent
- XMLAgent
- Agent --> <name>Agent # Examples: ZeroShotAgent, ChatAgent
-
-
- BaseMultiActionAgent --> OpenAIMultiFunctionsAgent
-
-
-**Main helpers:**
-
-.. code-block::
-
- AgentType, AgentExecutor, AgentOutputParser, AgentExecutorIterator,
- AgentAction, AgentFinish, AgentStep
+1. Given a prompt an agent uses an LLM to request an action to take (e.g., a tool to run).
+2. The agent executes the action (e.g., runs the tool), and receives an observation.
+3. The agent returns the observation to the LLM, which can then be used to generate the next action.
+4. When the agent reaches a stopping condition, it returns a final return value.
+The schemas for the agents themselves are defined in langchain.agents.agent.
""" # noqa: E501
from __future__ import annotations
@@ -43,7 +36,11 @@ from langchain_core.messages import (
class AgentAction(Serializable):
- """A full description of an action for an ActionAgent to execute."""
+ """Represents a request to execute an action by an agent.
+
+ The action consists of the name of the tool to execute and the input to pass
+ to the tool. The log is used to pass along extra information about the action.
+ """
tool: str
"""The name of the Tool to execute."""
@@ -59,10 +56,10 @@ class AgentAction(Serializable):
before the tool/tool_input)."""
type: Literal["AgentAction"] = "AgentAction"
+ # Override init to support instantiation by position for backward compat.
def __init__(
self, tool: str, tool_input: Union[str, dict], log: str, **kwargs: Any
):
- """Override init to support instantiation by position for backward compat."""
super().__init__(tool=tool, tool_input=tool_input, log=log, **kwargs)
@classmethod
@@ -82,6 +79,13 @@ class AgentAction(Serializable):
class AgentActionMessageLog(AgentAction):
+ """A representation of an action to be executed by an agent.
+
+ This is similar to AgentAction, but includes a message log consisting of
+ chat messages. This is useful when working with ChatModels, and is used
+ to reconstruct conversation history from the agent's perspective.
+ """
+
message_log: Sequence[BaseMessage]
"""Similar to log, this can be used to pass along extra
information about what exact messages were predicted by the LLM
@@ -111,7 +115,10 @@ class AgentStep(Serializable):
class AgentFinish(Serializable):
- """The final return value of an ActionAgent."""
+ """The final return value of an ActionAgent.
+
+ Agents return an AgentFinish when they have reached a stopping condition.
+ """
return_values: dict
"""Dictionary of return values."""