python

agentcontextos — Python SDK

Official Python client for the AgentContextOS RAG gateway. It wraps every gateway REST route — query, retrieve, corpora, ingest, the OpenAI-compatible embeddings/chat/models surface, and the streaming agent runtime — with sync and async clients that share one set of typed wire models (rag-core).

Install

pip install agentcontextos
# gRPC transport (optional):
pip install "agentcontextos[grpc]"

Quick start

from agentcontextos import Client

with Client("http://localhost:8000", tenant_id="acme", principal_id="svc") as rag:
    # Retrieval-only
    hits = rag.retrieve("How do I rotate signing keys?", top_k=5)

    # Full RAG (optionally with an LLM answer)
    resp = rag.query("How do I rotate signing keys?", generate=True)
    print(resp.answer.text if resp.answer else [c.content for c in resp.chunks])

    # OpenAI-compatible chat with retrieval pre-fetch
    chat = rag.chat([{"role": "user", "content": "Summarise our key-rotation policy"}])
    print(chat.choices[0].message.content)

Streaming

for chunk in rag.stream_chat([{"role": "user", "content": "Explain HNSW"}]):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

for event in rag.stream_agent("Find and summarise the on-call runbook"):
    print(event.kind, event.phase)
result = rag.agent("Find and summarise the on-call runbook")  # run to completion

Async

from agentcontextos import AsyncClient

async with AsyncClient(url, tenant_id="acme", principal_id="svc") as rag:
    resp = await rag.query("...")
    async for chunk in rag.stream_chat([{"role": "user", "content": "hi"}]):
        ...

Identity

Configure identity once on the client; the SDK applies it the way each route expects (request body for query/retrieve/agent, headers for the rest):

• Dev / demo: pass tenant_id + principal_id.
• Production: pass api_key (sent as Authorization: Bearer …) and tenant_id.

Per-call tenant_id / principal_id arguments override the client defaults.

Errors

Non-2xx responses raise an ApiError subclass keyed by status: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429), ServerError (5xx). Each carries .code, .message, and .request_id.

Framework integrations

Drop the gateway into your agent / RAG framework as a native retriever or tool. Install the matching extra and import from agentcontextos.integrations:

pip install "agentcontextos[langchain]"   # or llama-index / haystack / dspy /
                                          #    langgraph / crewai / autogen / semantic-kernel

from agentcontextos.integrations.langchain import AgentContextOSRetriever

retriever = AgentContextOSRetriever(
    base_url="http://localhost:8000", tenant_id="acme", principal_id="svc", top_k=5
)
docs = retriever.invoke("How do I rotate signing keys?")

Supported: LangChain, LlamaIndex, Haystack, DSPy, LangGraph, CrewAI, AutoGen, Semantic Kernel. See docs/reference/integrations.md.

Versioning

This SDK is hand-written but reviewed against the committed dist/openapi.json (the same spec that generates the Go / Java / .NET clients) and proto/rag.proto. See docs/reference/sdks.md.