Google ADK

import { Callout } from '/snippets/callout.mdx';

The Agent Development Kit (ADK) is Google's open-source framework for building AI agents. Chroma integrates with ADK via the Chroma MCP server, giving your agents access to semantic memory, knowledge base retrieval, and persistent context across sessions.

Prerequisites

Python 3.10+
uvx installed (curl -LsSf https://astral.sh/uv/install.sh | sh)

Setup

<Tabs> <Tab title="Chroma Cloud"> <Callout> [Chroma Cloud](https://trychroma.com/signup?utm_source=docs-adk) is a fully managed, serverless database-as-a-service. Get started in 30 seconds - $5 in free credits included. </Callout> <Steps titleSize="h3"> <Step title="Install and log in"> <CodeGroup> ```bash pip pip install chromadb google-adk ``` ```bash uv uv pip install chromadb google-adk ``` </CodeGroup>

Then authenticate with Chroma Cloud:

```bash
chroma login
```

</Step> <Step title="Create a database"> ```bash chroma db create my-adk-db ``` </Step> <Step title="Get your connection variables"> ```bash chroma db connect my-adk-db --env-vars ```

This will output your `CHROMA_TENANT`, `CHROMA_DATABASE`, and `CHROMA_API_KEY`. Use them in the code below.

</Step> <Step title="Create your agent"> ```python Python from google.adk.agents import Agent from google.adk.tools.mcp_tool import McpToolset from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams from mcp import StdioServerParameters

CHROMA_TENANT = "your-tenant-id"
CHROMA_DATABASE = "my-adk-db"
CHROMA_API_KEY = "your-api-key"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="chroma_agent",
    instruction="Help users store and retrieve information using semantic search.",
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="uvx",
                    args=[
                        "chroma-mcp",
                        "--client-type", "cloud",
                        "--tenant", CHROMA_TENANT,
                        "--database", CHROMA_DATABASE,
                        "--api-key", CHROMA_API_KEY,
                    ],
                ),
                timeout=30,
            ),
        )
    ],
)
```

</Step> </Steps>

Example: Semantic Memory Agent

This example builds a personal assistant that uses Chroma as a persistent semantic memory store. The agent remembers facts from past conversations — user preferences, project context, decisions — and recalls them when relevant.

The agent's instruction tells it to create a Chroma collection for storing memories, and to use it for storage and retrieval:

python

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

CHROMA_TENANT = "your-tenant-id"
CHROMA_DATABASE = "my-adk-db"
CHROMA_API_KEY = "your-api-key"

MEMORY_INSTRUCTION = """You are a personal assistant with persistent memory.

You have access to Chroma tools for managing collections and documents.

## First run
On your first interaction, use chroma_create_collection to create a collection
called "memory". If it already exists, that's fine — just use the existing one.

## Storing memories
When the user shares important information — preferences, project details,
decisions, or personal context — store it in the "memory" collection using
chroma_add_documents. Each memory should be a concise, self-contained fact.
Tag memories with metadata like {"type": "preference"}, {"type": "fact"},
or {"type": "decision"} so they can be filtered later.

## Recalling memories
At the start of a conversation, or when the user asks about something that
might relate to past context, use chroma_query_documents to search the
"memory" collection. Use the results to inform your responses without
the user having to repeat themselves.

## Memory hygiene
If the user corrects a previous fact, use chroma_update_documents to update
the old memory rather than creating a duplicate.
"""

root_agent = Agent(
    model="gemini-2.5-pro",
    name="memory_agent",
    instruction=MEMORY_INSTRUCTION,
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="uvx",
                    args=[
                        "chroma-mcp",
                        "--client-type", "cloud",
                        "--tenant", CHROMA_TENANT,
                        "--database", CHROMA_DATABASE,
                        "--api-key", CHROMA_API_KEY,
                    ],
                ),
                timeout=30,
            ),
        )
    ],
)

With this setup, a conversation might look like:

text

User: I'm working on Project Atlas — it's a migration from PostgreSQL to
      DynamoDB. Our deadline is end of Q3 and the team lead is Sarah.

Agent: Got it, I've stored those project details. I'll remember them for
       future conversations.
       (creates "memory" collection, stores 3 memories: project description,
       deadline, team lead)

--- later session ---

User: What do you remember about my current project?

Agent: You're working on Project Atlas — a PostgreSQL to DynamoDB migration.
       Sarah is the team lead and your deadline is end of Q3.
       (retrieved via semantic search on "current project")

For a more in-depth look at building agentic memory with Chroma, see the Agentic Memory guide.

</Tab> <Tab title="Local">

Install the dependencies:

<CodeGroup> ```bash pip pip install chromadb google-adk ``` ```bash uv uv pip install chromadb google-adk ``` </CodeGroup>

Replace /path/to/your/data/directory with where you want Chroma to store its data.

python

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

DATA_DIR = "/path/to/your/data/directory"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="chroma_agent",
    instruction="Help users store and retrieve information using semantic search.",
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="uvx",
                    args=[
                        "chroma-mcp",
                        "--client-type", "persistent",
                        "--data-dir", DATA_DIR,
                    ],
                ),
                timeout=30,
            ),
        )
    ],
)

Example: Semantic Memory Agent

The agent's instruction tells it to create a Chroma collection for storing memories, and to use it for storage and retrieval:

python

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

DATA_DIR = "/path/to/your/data/directory"

MEMORY_INSTRUCTION = """You are a personal assistant with persistent memory.

You have access to Chroma tools for managing collections and documents.

## First run
On your first interaction, use chroma_create_collection to create a collection
called "memory". If it already exists, that's fine — just use the existing one.

## Storing memories
When the user shares important information — preferences, project details,
decisions, or personal context — store it in the "memory" collection using
chroma_add_documents. Each memory should be a concise, self-contained fact.
Tag memories with metadata like {"type": "preference"}, {"type": "fact"},
or {"type": "decision"} so they can be filtered later.

## Recalling memories
At the start of a conversation, or when the user asks about something that
might relate to past context, use chroma_query_documents to search the
"memory" collection. Use the results to inform your responses without
the user having to repeat themselves.

## Memory hygiene
If the user corrects a previous fact, use chroma_update_documents to update
the old memory rather than creating a duplicate.
"""

root_agent = Agent(
    model="gemini-2.5-pro",
    name="memory_agent",
    instruction=MEMORY_INSTRUCTION,
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="uvx",
                    args=[
                        "chroma-mcp",
                        "--client-type", "persistent",
                        "--data-dir", DATA_DIR,
                    ],
                ),
                timeout=30,
            ),
        )
    ],
)

With this setup, a conversation might look like:

text

User: I'm working on Project Atlas — it's a migration from PostgreSQL to
      DynamoDB. Our deadline is end of Q3 and the team lead is Sarah.

Agent: Got it, I've stored those project details. I'll remember them for
       future conversations.
       (creates "memory" collection, stores 3 memories: project description,
       deadline, team lead)

--- later session ---

User: What do you remember about my current project?

Agent: You're working on Project Atlas — a PostgreSQL to DynamoDB migration.
       Sarah is the team lead and your deadline is end of Q3.
       (retrieved via semantic search on "current project")

For a more in-depth look at building agentic memory with Chroma, see the Agentic Memory guide.

</Tab> </Tabs> </Tab> <Tab title="TypeScript" icon="js">

Prerequisites

Node.js 18+
uvx installed (curl -LsSf https://astral.sh/uv/install.sh | sh)

Setup

<CodeGroup>
```bash npm
npm install @google/adk
```
```bash pnpm
pnpm add @google/adk
```
```bash yarn
yarn add @google/adk
```
</CodeGroup>

Install the Chroma CLI and authenticate:

<CodeGroup>
```bash pip
pip install chromadb
```
```bash uv
uv pip install chromadb
```
</CodeGroup>

```bash
chroma login
```

</Step> <Step title="Create a database"> ```bash chroma db create my-adk-db ``` </Step> <Step title="Get your connection variables"> ```bash chroma db connect my-adk-db --env-vars ```

This will output your `CHROMA_TENANT`, `CHROMA_DATABASE`, and `CHROMA_API_KEY`. Use them in the code below.

</Step> <Step title="Create your agent"> ```typescript TypeScript import { LlmAgent, MCPToolset } from "@google/adk";

const CHROMA_TENANT = "your-tenant-id";
const CHROMA_DATABASE = "my-adk-db";
const CHROMA_API_KEY = "your-api-key";

const rootAgent = new LlmAgent({
    model: "gemini-2.5-pro",
    name: "chroma_agent",
    instruction: "Help users store and retrieve information using semantic search.",
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "uvx",
                args: [
                    "chroma-mcp",
                    "--client-type", "cloud",
                    "--tenant", CHROMA_TENANT,
                    "--database", CHROMA_DATABASE,
                    "--api-key", CHROMA_API_KEY,
                ],
            },
        }),
    ],
});
```

</Step> </Steps>

Example: Semantic Memory Agent

The agent's instruction tells it to create a Chroma collection for storing memories, and to use it for storage and retrieval:

typescript

import { LlmAgent, MCPToolset } from "@google/adk";

const CHROMA_TENANT = "your-tenant-id";
const CHROMA_DATABASE = "my-adk-db";
const CHROMA_API_KEY = "your-api-key";

const MEMORY_INSTRUCTION = `You are a personal assistant with persistent memory.

You have access to Chroma tools for managing collections and documents.

## First run
On your first interaction, use chroma_create_collection to create a collection
called "memory". If it already exists, that's fine — just use the existing one.

## Storing memories
When the user shares important information — preferences, project details,
decisions, or personal context — store it in the "memory" collection using
chroma_add_documents. Each memory should be a concise, self-contained fact.
Tag memories with metadata like {"type": "preference"}, {"type": "fact"},
or {"type": "decision"} so they can be filtered later.

## Recalling memories
At the start of a conversation, or when the user asks about something that
might relate to past context, use chroma_query_documents to search the
"memory" collection. Use the results to inform your responses without
the user having to repeat themselves.

## Memory hygiene
If the user corrects a previous fact, use chroma_update_documents to update
the old memory rather than creating a duplicate.
`;

const rootAgent = new LlmAgent({
    model: "gemini-2.5-pro",
    name: "memory_agent",
    instruction: MEMORY_INSTRUCTION,
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "uvx",
                args: [
                    "chroma-mcp",
                    "--client-type", "cloud",
                    "--tenant", CHROMA_TENANT,
                    "--database", CHROMA_DATABASE,
                    "--api-key", CHROMA_API_KEY,
                ],
            },
        }),
    ],
});

With this setup, a conversation might look like:

text

User: I'm working on Project Atlas — it's a migration from PostgreSQL to
      DynamoDB. Our deadline is end of Q3 and the team lead is Sarah.

Agent: Got it, I've stored those project details. I'll remember them for
       future conversations.
       (creates "memory" collection, stores 3 memories: project description,
       deadline, team lead)

--- later session ---

User: What do you remember about my current project?

Agent: You're working on Project Atlas — a PostgreSQL to DynamoDB migration.
       Sarah is the team lead and your deadline is end of Q3.
       (retrieved via semantic search on "current project")

For a more in-depth look at building agentic memory with Chroma, see the Agentic Memory guide.

</Tab> <Tab title="Local">

Install the ADK package:

<CodeGroup> ```bash npm npm install @google/adk ``` ```bash pnpm pnpm add @google/adk ``` ```bash yarn yarn add @google/adk ``` </CodeGroup>

Replace /path/to/your/data/directory with where you want Chroma to store its data.

typescript

import { LlmAgent, MCPToolset } from "@google/adk";

const DATA_DIR = "/path/to/your/data/directory";

const rootAgent = new LlmAgent({
    model: "gemini-2.5-pro",
    name: "chroma_agent",
    instruction: "Help users store and retrieve information using semantic search.",
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "uvx",
                args: [
                    "chroma-mcp",
                    "--client-type", "persistent",
                    "--data-dir", DATA_DIR,
                ],
            },
        }),
    ],
});

Example: Semantic Memory Agent

The agent's instruction tells it to create a Chroma collection for storing memories, and to use it for storage and retrieval:

typescript

import { LlmAgent, MCPToolset } from "@google/adk";

const DATA_DIR = "/path/to/your/data/directory";

const MEMORY_INSTRUCTION = `You are a personal assistant with persistent memory.

You have access to Chroma tools for managing collections and documents.

## First run
On your first interaction, use chroma_create_collection to create a collection
called "memory". If it already exists, that's fine — just use the existing one.

## Storing memories
When the user shares important information — preferences, project details,
decisions, or personal context — store it in the "memory" collection using
chroma_add_documents. Each memory should be a concise, self-contained fact.
Tag memories with metadata like {"type": "preference"}, {"type": "fact"},
or {"type": "decision"} so they can be filtered later.

## Recalling memories
At the start of a conversation, or when the user asks about something that
might relate to past context, use chroma_query_documents to search the
"memory" collection. Use the results to inform your responses without
the user having to repeat themselves.

## Memory hygiene
If the user corrects a previous fact, use chroma_update_documents to update
the old memory rather than creating a duplicate.
`;

const rootAgent = new LlmAgent({
    model: "gemini-2.5-pro",
    name: "memory_agent",
    instruction: MEMORY_INSTRUCTION,
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "uvx",
                args: [
                    "chroma-mcp",
                    "--client-type", "persistent",
                    "--data-dir", DATA_DIR,
                ],
            },
        }),
    ],
});

With this setup, a conversation might look like:

text

User: I'm working on Project Atlas — it's a migration from PostgreSQL to
      DynamoDB. Our deadline is end of Q3 and the team lead is Sarah.

Agent: Got it, I've stored those project details. I'll remember them for
       future conversations.
       (creates "memory" collection, stores 3 memories: project description,
       deadline, team lead)

--- later session ---

User: What do you remember about my current project?

Agent: You're working on Project Atlas — a PostgreSQL to DynamoDB migration.
       Sarah is the team lead and your deadline is end of Q3.
       (retrieved via semantic search on "current project")

For a more in-depth look at building agentic memory with Chroma, see the Agentic Memory guide.

</Tab> </Tabs> </Tab> </Tabs>

Available Tools

Once connected, your ADK agent will have access to the following Chroma tools:

Collection Management

Tool	Description
`chroma_list_collections`	List all collections with pagination support
`chroma_create_collection`	Create a new collection with optional HNSW configuration
`chroma_get_collection_info`	Get detailed information about a collection
`chroma_get_collection_count`	Get the number of documents in a collection
`chroma_modify_collection`	Update a collection's name or metadata
`chroma_delete_collection`	Delete a collection
`chroma_peek_collection`	View a sample of documents in a collection

Document Operations

Tool	Description
`chroma_add_documents`	Add documents with optional metadata and custom IDs
`chroma_query_documents`	Query documents using semantic search with advanced filtering
`chroma_get_documents`	Retrieve documents by IDs or filters with pagination
`chroma_update_documents`	Update existing documents' content, metadata, or embeddings
`chroma_delete_documents`	Delete specific documents from a collection

Prerequisites

Setup

Example: Semantic Memory Agent

Example: Semantic Memory Agent

Prerequisites

Setup

Example: Semantic Memory Agent

Example: Semantic Memory Agent

Available Tools

Collection Management

Document Operations

Resources