Skip to content

integrations.md

Latest commit

 

History

History
156 lines (115 loc) · 5.92 KB

integrations.md

File metadata and controls

156 lines (115 loc) · 5.92 KB
Raw

Framework adapters

Drop-in integrations that expose the AgentContextOS gateway as a native retriever / tool / knowledge source inside popular agent + RAG frameworks. They live in the Python SDK under agentcontextos.integrations.<framework> and wrap the public agentcontextos.Client.

Overview

Framework Extra Module Native type / entry point
LangChain langchain agentcontextos.integrations.langchain AgentContextOSRetriever(BaseRetriever)
LlamaIndex llama-index agentcontextos.integrations.llama_index AgentContextOSRetriever(BaseRetriever)
Haystack haystack agentcontextos.integrations.haystack AgentContextOSRetriever (@component)
DSPy dspy agentcontextos.integrations.dspy AgentContextOSRM (retrieval model)
LangGraph langgraph agentcontextos.integrations.langgraph make_retrieval_tool / make_retrieval_node
CrewAI crewai agentcontextos.integrations.crewai AgentContextOSSearchTool(BaseTool)
AutoGen autogen agentcontextos.integrations.autogen make_search_function / make_function_tool
Semantic Kernel semantic-kernel agentcontextos.integrations.semantic_kernel AgentContextOSPlugin

Install only what you use:

pip install "agentcontextos[langchain]"

Importing agentcontextos.integrations pulls in no framework; each submodule imports its framework lazily and raises a clear "install the extra" message if it's absent.

Common configuration

Every adapter accepts the same two ways to supply a client, plus the same retrieval knobs:

  • Inject a client — pass a configured agentcontextos.Client (or AsyncClient where supported) as client= / async_client=.
  • Connection kwargs — pass base_url, tenant_id, principal_id, api_key; the adapter builds the client.
  • Retrieval knobs — top_k, corpus_ids, rerank (and filters on the retriever adapters).

Retrieval runs through /v1/query with pack=False / generate=False, so each gateway chunk arrives hydrated (content + score) and is mapped to the framework's document type. The canonical metadata each adapter attaches: chunk_id, document_id, tenant_id, corpus_id, score, trust_level, plus the chunk's own metadata.

Usage

LangChain

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?")     # list[Document]
docs = await retriever.ainvoke("...")                         # async path

LlamaIndex

from agentcontextos.integrations.llama_index import AgentContextOSRetriever

retriever = AgentContextOSRetriever(client=my_client, top_k=5)
nodes = retriever.retrieve("How do I rotate signing keys?")   # list[NodeWithScore]

Haystack

from agentcontextos.integrations.haystack import AgentContextOSRetriever

retriever = AgentContextOSRetriever(base_url=..., tenant_id="acme", principal_id="svc")
docs = retriever.run(query="How do I rotate signing keys?")["documents"]
# wire it into a haystack Pipeline like any retriever component

DSPy

import dspy
from agentcontextos.integrations.dspy import AgentContextOSRM

dspy.settings.configure(rm=AgentContextOSRM(client=my_client, k=5))
passages = dspy.Retrieve(k=5)("How do I rotate signing keys?").passages

LangGraph

from agentcontextos.integrations.langgraph import make_retrieval_tool, make_retrieval_node

tool = make_retrieval_tool(client=my_client, top_k=5)        # StructuredTool → ToolNode
node = make_retrieval_node(client=my_client, input_key="question", output_key="docs")
# graph.add_node("retrieve", node)

CrewAI

from agentcontextos.integrations.crewai import AgentContextOSSearchTool

tool = AgentContextOSSearchTool(client=my_client, top_k=5)
# Agent(role=..., tools=[tool], ...)

AutoGen

from agentcontextos.integrations.autogen import make_search_function, make_function_tool

search = make_search_function(client=my_client, top_k=5)     # plain callable
tool = make_function_tool(client=my_client, top_k=5)         # autogen_core FunctionTool

Semantic Kernel

import semantic_kernel as sk
from agentcontextos.integrations.semantic_kernel import AgentContextOSPlugin

kernel = sk.Kernel()
kernel.add_plugin(AgentContextOSPlugin(client=my_client, top_k=5), plugin_name="agentcontextos")

Internals

  • _common.py owns the shared pieces: client resolution (resolve_sync_client / resolve_async_client), the retrieval call (retrieve / aretrieve), the Chunk → (text, metadata) mapping (chunk_text / chunk_metadata), and the tool-string rendering (format_passages, used by the CrewAI / AutoGen / Semantic Kernel tools).
  • The retriever adapters (LangChain, LlamaIndex, Haystack, LangGraph) return framework documents; the tool adapters (CrewAI, AutoGen, Semantic Kernel) return a rendered passage string the model reads back.

Extension points

  • Add a framework — create integrations/<framework>.py that lazy-imports the framework (re-raising via missing_dependency), wraps a resolved client, and maps chunks with the _common helpers; add a [<extra>] to the SDK pyproject, a mypy override for the framework module, and an importorskip test.
  • Change the retrieval shape — adjust RetrievalOptions / retrieve in _common.py; every adapter inherits the change.

See also