Agents API

An agent drives the conversation loop: it sends messages to a provider, executes any tool calls the model returns, feeds the results back, and repeats until the model answers without calling a tool.

from ToolAgents.agents import ChatToolAgent, AsyncChatToolAgent

ChatToolAgent

ChatToolAgent

ChatToolAgent(
    chat_api: ChatAPIProvider,
    log_output: bool = False,
    log_to_file: bool = False,
    observability_handler: (
        AgentObservabilityHandler | None
    ) = None,
)

Bases: BaseToolAgent

AsyncChatToolAgent

AsyncChatToolAgent

AsyncChatToolAgent(
    chat_api: AsyncChatAPIProvider,
    debug_output: bool = False,
    observability_handler: (
        AgentObservabilityHandler | None
    ) = None,
)

Bases: AsyncBaseToolAgent

Base classes

Implement these to write an agent of your own.

BaseToolAgent

BaseToolAgent(
    observability_handler: (
        AgentObservabilityHandler | None
    ) = None,
)

Bases: ABC

step abstractmethod

step(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> ChatMessage

Performs a single step of interaction with the agent, returning the chat message of the agent .

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Returns:

Type	Description
ChatMessage	Chat Message (ChatMessage)

stream_step abstractmethod

stream_step(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> Generator[StreamingChatMessage, None, None]

Performs a single streaming step of interaction with the agent, yielding chunks.

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Yields:

Type	Description
StreamingChatMessage	Chunks of chat api responses (StreamingChatAPIResponse)

get_response abstractmethod

get_response(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> ChatResponse

Gets a complete response from the chat API, handling any tool calls.

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Returns:

Type	Description
ChatResponse	The final chat response from the agent.(ChatResponse)

get_streaming_response abstractmethod

get_streaming_response(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> Generator[ChatResponseChunk, None, None]

Gets a streaming response from the chat API, handling any tool calls.

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Yields:

Type	Description
ChatResponseChunk	Response chunks(ChatResponseChunk)

get_last_response abstractmethod

get_last_response() -> ChatResponse

Returns the last response from the agent. Returns: Last response(ChatResponse)

AsyncBaseToolAgent

AsyncBaseToolAgent(
    observability_handler: (
        AgentObservabilityHandler | None
    ) = None,
)

Bases: ABC

step abstractmethod async

step(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> ChatMessage

Performs a single step of interaction with the agent, returning the chat message of the agent .

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Returns:

Type	Description
ChatMessage	Chat Message (ChatMessage)

stream_step abstractmethod async

stream_step(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> Generator[StreamingChatMessage, None, None]

Performs a single streaming step of interaction with the agent, yielding chunks.

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Yields:

Type	Description
StreamingChatMessage	Chunks of chat api responses (StreamingChatAPIResponse)

get_response abstractmethod async

get_response(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> ChatResponse

Gets a complete response from the chat API, handling any tool calls.

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Returns:

Type	Description
ChatResponse	The final chat response from the agent.(ChatResponse)

get_streaming_response abstractmethod async

get_streaming_response(
    messages: List[ChatMessage],
    tool_registry: ToolRegistry = None,
    settings: Optional[ProviderSettings] = None,
    reset_last_messages_buffer: bool = True,
) -> AsyncGenerator[ChatResponseChunk, None]

Gets a streaming response from the chat API, handling any tool calls.

Parameters:

Name	Type	Description	Default
messages	List[ChatMessage]	List of message dictionaries	required
tool_registry	ToolRegistry	Optional ToolRegistry containing available tools	None
settings	Optional[ProviderSettings]	Optional settings for the API call	None
reset_last_messages_buffer	bool	Whether to reset the message buffer	True

Yields:

Type	Description
AsyncGenerator[ChatResponseChunk, None]	Response chunks(ChatResponseChunk)

get_last_response abstractmethod

get_last_response() -> ChatResponse

Returns the last response from the agent. Returns: Last response(ChatResponse)

Observability

AgentObservabilityHandler

Bases: ABC

Responses

ChatResponse

Bases: BaseModel

Represents an agent chat response.

ChatResponseChunk

Bases: BaseModel

Represents an agent chat response chunk.