Agent Squad Integration

DakeraRetriever plugs Dakera's server-side semantic search into Agent Squad agents as a retriever. Attach it to an agent and every turn is grounded in the most relevant memories from a Dakera namespace — no local embedding model, in Python, TypeScript, or Swift.

Overview

Agent Squad (formerly the AWS Multi-Agent Orchestrator) routes each user message to the best agent in a squad and streams back its answer. Any agent can carry a retriever — an object the framework calls to fetch supporting context before the LLM generates. DakeraRetriever is that object, backed by a self-hosted Dakera memory server: it queries a Dakera namespace over Dakera's text-query API and hands the agent the most relevant stored documents to answer from.

Embedding happens server-side — the retriever sends raw query text and Dakera embeds, ranks, and returns matches. Nothing about the integration ships a local embedding model, ONNX runtime, or vector index into your process, in any of the three supported languages.

When to use it

• You already run (or will run) a Dakera server and want an Agent Squad agent to answer from what lives there.
• You want persistent, decay-weighted recall across sessions rather than a per-request, in-memory vector store.
• You want the same retrieval behaviour across a Python backend, a TypeScript/Node service, and a Swift app — one API, three ports.
• You want retrieval and generation to stay cleanly separated: Dakera ranks context, your agent's LLM writes the answer.

How a retriever fits the orchestrator

The orchestrator itself doesn't call Dakera. It classifies the incoming message, picks an agent, and invokes it; the agent owns the retriever. When the selected agent has a DakeraRetriever, the framework calls the retriever with the user's query, folds the returned text into the prompt as grounding context, and only then runs the model. Add a retriever to one agent, several agents, or every agent — each queries whatever namespace (and filter) you configured for it.

Quick Start

git clone https://github.com/dakera-ai/dakera-deploy
cd dakera-deploy && docker compose up -d   # API on :3000

# Python — the [dakera] extra pulls in the dakera SDK (>= 0.12.8)
pip install "agent-squad[dakera]"

# TypeScript — Dakera SDK is an optional peer dependency
npm install agent-squad @dakera-ai/dakera

# Swift — add the package; no third-party SDK needed
# .package(url: "https://github.com/2FastLabs/agent-squad", ...)

export DAKERA_URL="http://localhost:3000"
export DAKERA_API_KEY="dk-..."

Attach the retriever to an agent

from agent_squad.agents import BedrockLLMAgent, BedrockLLMAgentOptions
from agent_squad.retrievers import DakeraRetriever, DakeraRetrieverOptions

orchestrator.add_agent(
    BedrockLLMAgent(BedrockLLMAgentOptions(
        name="My personal agent",
        description="Answers questions using context retrieved from Dakera.",
        streaming=True,
        inference_config={"temperature": 0.1},
        retriever=DakeraRetriever(DakeraRetrieverOptions(
            namespace="my-docs",
            top_k=5,
        )),
    ))
)

TypeScript

The TypeScript port has the same shape — pass a DakeraRetriever as the agent's retriever. Options are camelCased (topK rather than top_k).

import { BedrockLLMAgent, DakeraRetriever } from "agent-squad";

orchestrator.addAgent(
  new BedrockLLMAgent({
    name: "My personal agent",
    description: "Answers questions using context retrieved from Dakera.",
    streaming: true,
    inferenceConfig: { temperature: 0.1 },
    retriever: new DakeraRetriever({ namespace: "my-docs", topK: 5 }),
  })
);

Swift

The Swift SDK grounds answers through tools rather than a Retriever base class, so DakeraRetriever is a ToolProvider: hand it to an Agent or GroundedAgent and the model can call a search_memory tool to ground its answers on remembered facts. The same type also exposes a direct retrieve(_:) API for manual RAG. It talks to Dakera's REST API over URLSession — no third-party SDK is pulled into the package.

import AgentSquad

// As a tool provider — the agent can call the search_memory tool
let memory = DakeraRetriever(
    namespace: "my-docs",
    apiKey: "dk-...",          // or the DAKERA_API_KEY env var
    url: "http://localhost:3000",
    topK: 5
)

// Direct retrieval — each hit is a DakeraDocument (.id / .content / .score / .metadata)
let docs = try await memory.retrieve("what does the user prefer?")
let context = try await memory.retrieveAndCombineResults("what does the user prefer?")

Standalone retrieval

DakeraRetriever is async and uses Dakera's text-query API (server-side embedding). retrieve returns the raw ranked results; retrieve_and_combine_results joins their text into a single newline-separated context string ready to pass to an LLM (results with no text are skipped).

import asyncio
from agent_squad.retrievers import DakeraRetriever, DakeraRetrieverOptions

retriever = DakeraRetriever(DakeraRetrieverOptions(namespace="my-docs", top_k=5))

# Raw results — each has .id / .score / .text / .metadata
results = asyncio.run(retriever.retrieve("How many languages are spoken worldwide?"))
for r in results:
    print(r.id, r.score, r.text)

# Or a single combined context string, ready to hand to an LLM
context = asyncio.run(
    retriever.retrieve_and_combine_results("How many languages are spoken worldwide?")
)

Per-call overrides (Python)

In Python, retrieve and retrieve_and_combine_results accept optional top_k and metadata_filter arguments that override the options for a single call — useful when one agent needs a wider or more narrowly filtered pull than its default:

# Override the configured top_k and filter for this query only
results = await retriever.retrieve(
    "quarterly revenue",
    top_k=20,
    metadata_filter={"lang": {"$eq": "en"}},
)

The TypeScript and Swift retrieve methods take the query text only and use the values from the options object.

Return shape

Each result is one match from Dakera's text query. In Python and TypeScript the results are TextSearchResult objects with id, score, text, and metadata. In Swift each hit is a DakeraDocument with the same data, except the text field is named content:

DakeraRetrieverOptions

The same five options exist in every language (names differ only in casing). Swift adds three more for its tool-provider role.

Methods by language

The retrieval surface is small and consistent. Python and TypeScript extend the framework Retriever; Swift is a ToolProvider that also offers direct retrieval.

Configuring via environment

Rather than hard-coding credentials, set DAKERA_API_KEY (and optionally DAKERA_URL) in the environment and construct the retriever with just a namespace — every language reads those two variables as fallbacks:

export DAKERA_API_KEY="dk-..."
export DAKERA_URL="http://localhost:3000"

# api_key and url now come from the environment
retriever = DakeraRetriever(DakeraRetrieverOptions(namespace="my-docs", top_k=5))

Scoping what a retriever sees

Two options control the search surface. namespace (required) isolates one set of memories from another — give each agent, tenant, or document collection its own namespace and their contexts never bleed together. The optional filter narrows within a namespace using a Dakera metadata filter, so one namespace can back several agents that each see only their slice. Leave filter unset to search the whole namespace.

# One namespace, two agents, different slices via metadata filter
support = DakeraRetriever(DakeraRetrieverOptions(
    namespace="kb",
    filter={"team": {"$eq": "support"}},
))
billing = DakeraRetriever(DakeraRetrieverOptions(
    namespace="kb",
    filter={"team": {"$eq": "billing"}},
))

The filter is passed straight through to Dakera's text-query API — the same metadata-filter syntax you use elsewhere in Dakera (for example {"lang": {"$eq": "en"}}). In TypeScript the field is typed as a FilterExpression; in Swift it is any JSONValue.

Retrieval-only by design

DakeraRetriever deliberately does not generate answers. In Python and TypeScript it extends the framework's Retriever base class and implements two methods — retrieve and retrieve_and_combine_results — while the third the base class defines, retrieve_and_generate, is overridden to raise (Python raises NotImplementedError; TypeScript throws) with a message directing you to the retrieval methods. The rationale is a clean split of concerns: Dakera's job is to rank and return the most relevant context, and your agent's LLM (Bedrock, OpenAI, or whatever the agent wraps) writes the response from it. That keeps the agent process light — no generation model bundled into the retriever — and lets you swap the answering model freely.

Populating the namespace

Because DakeraRetriever is retrieval-only, the memories it searches are written separately — the retriever reads whatever already lives in the namespace. Populate it with the Dakera SDK or REST API (its text-upsert endpoint embeds server-side, mirroring the text-query the retriever uses), or point another Dakera integration at the same namespace. Any agent with a DakeraRetriever on that namespace then grounds its answers in that content.

How it works

1. Each turn, the agent calls the retriever with the user's query.
2. DakeraRetriever sends that query to Dakera's text-query API, which embeds it server-side — no embedding model runs inside your agent, in any of the three languages.
3. Dakera returns the top_k most relevant memories from the namespace (optionally narrowed by filter), each with an id, score, text, and metadata.
4. retrieve_and_combine_results flattens those into a single context string; your agent's LLM answers from it. Generation stays entirely on your side.

Under the hood the query is a single call to Dakera's text-query endpoint (POST /v1/namespaces/{namespace}/query-text), authenticated with an X-API-Key header and carrying the query text, top_k, and any filter. The Python and TypeScript ports make that call through the official Dakera SDK; the Swift port issues the request directly over URLSession. The API key travels only as a header — it is never logged, echoed into arguments, or included in the tool trace.

Troubleshooting

Related integrations

Links

• Source PR — 2FastLabs/agent-squad #553
• Dakera deploy — Docker Compose setup
• Dakera quickstart
• RAG-Augmented Memory pattern
• All integrations

Frequently Asked Questions