Skip to content

API Reference

The public API is exported from the agent package.

Agent

from agent import Agent

Agent is the high-level facade. It owns an LLM adapter, optional RAG backend, optional memory, conversation history, tool registry, callbacks and runtime.

Important methods:

  • Agent.run(user_input: str) -> str
  • Agent.stream(user_input: str) -> Iterable[str]
  • Agent.add_tool(tool, name=None, description=None) -> Tool
  • Agent.reset() -> None

Runtime

Runtime coordinates prompt construction, optional retrieval, LLM calls, tool execution, callback events and history persistence. Most applications should use Agent rather than calling Runtime directly.

RuntimeConfig

RuntimeConfig controls runtime behavior:

  • instructions
  • enable_rag
  • max_rag_results
  • rag_metadata_filter
  • max_tool_iterations
  • save_history
  • metadata

Messages

Message is a Pydantic model with role, content, optional name, and metadata. Valid roles are system, user, assistant, and tool.

ToolCall normalizes LLM tool requests with a tool name, arguments and optional call id.

PromptBuilder

PromptBuilder builds chat messages from:

  • system instructions
  • conversation history
  • recalled memory
  • retrieved RAG context
  • available tool schemas
  • current user input

ConversationHistory

ConversationHistory stores chat turns in memory.

Important methods:

  • add(message)
  • add_user(content)
  • add_assistant(content)
  • clear()
  • messages

Memory

Memory is a protocol:

class Memory(Protocol):
    def recall(self, query: str) -> str | None: ...
    def save(self, query: str, response: str) -> None: ...

InMemoryMemory is a simple implementation for examples, tests and local use.

Tools

Tool wraps a Python callable with a name, description and generated parameter schema.

ToolRegistry stores tools by name:

  • register(tool, name=None, description=None)
  • get(name)
  • schemas()
  • values()

ToolExecutor executes registered tools by name.

Callbacks

CallbackManager dispatches lifecycle events to callback objects when matching methods exist:

  • on_run_start(context)
  • on_llm_start(context, messages)
  • on_llm_end(context, response)
  • on_tool_start(context, tool_call)
  • on_tool_end(context, tool_call, output)
  • on_error(context, exc)
  • on_run_end(context, response)

RunContext includes input, run_id, and metadata.

Adapters

CallableLLM adapts a Python callable to the runtime LLM protocol.

OpenAIChatLLM adapts OpenAI Chat Completions. It requires the openai extra and supports completion and streaming.

RAG Integration

The runtime expects the public python-rag-framework retrieval API:

results = rag.retrieve(
    query,
    limit=4,
    metadata_filter=None,
)

Each result should expose chunk.text, chunk.metadata, and score, as provided by rag.SearchResult.