Skip to content

Architecture

python-agent-runtime is a small execution layer. It coordinates independent components rather than owning every AI concern.

Component Model

  • Agent is the public facade used by applications.
  • Runtime owns the execution loop.
  • PromptBuilder constructs chat messages.
  • ConversationHistory stores user and assistant turns.
  • Memory is an optional protocol for recalled context.
  • ToolRegistry stores tools and ToolExecutor invokes them.
  • CallbackManager emits lifecycle events.
  • RuntimeConfig keeps behavior explicit.

Execution Flow

  1. Agent.run() delegates to Runtime.
  2. The runtime recalls optional memory.
  3. If a rag.RAG instance is present, the runtime calls RAG.retrieve(...).
  4. PromptBuilder creates system, history and user messages.
  5. The LLM adapter is called.
  6. Structured tool calls are executed when returned.
  7. The final response is saved to history and memory.

RAG Boundary

The official retrieval backend is python-rag-framework. The runtime relies on its public retrieval API:

results = rag.retrieve(
    query,
    limit=4,
    metadata_filter={"language": "ko"},
)

Results are rag.SearchResult models containing chunk.text, chunk.metadata, and score.

The runtime does not duplicate ingestion, loaders, chunking, embeddings, vector stores, reranking, citations or RAG.ask() generation. Its role is to place retrieved context into the agent prompt.

LLM Boundary

The runtime defines a small protocol:

def complete(messages, *, tools=None) -> str | object: ...

Adapters can be application-specific. The package includes CallableLLM and OpenAIChatLLM for common use cases.

Design Principles

  • Prefer composition over inheritance.
  • Keep the public API small.
  • Keep provider and retrieval integrations optional.
  • Make the execution loop predictable.
  • Avoid workflow graphs, schedulers and orchestration engines.