> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Develop ADK Agents

> Build and package Google ADK agents for Orca Engine and deploy them with snctl.

This guide shows how to adapt Google Agent Development Kit (ADK) projects so they can run as Orca Agents on StreamNative Cloud. You will learn how to prepare an ADK project, expose the required `root_agent` entry point, and deploy the artifact with `snctl`.

## Prerequisites

* Python 3.10 or later and a virtual environment for packaging your agent code.
* The [`google-adk-python`](https://github.com/google/adk-python) library and any model SDKs your agent requires.
* The `orca-agent-engine` python SDK for orca engine.
* StreamNative CLI (`snctl`) installed and configured with the target organization, tenant, and namespace.
* Access to StreamNative Cloud topics that will deliver agent input and capture responses.

## Prepare an ADK project

1. Start from an ADK reference implementation. You can reuse examples from the Google ADK samples repository or the Orca engine examples provided below.

2. Copy the project into your own source repository and update the package metadata (for example, rename the module and adjust `pyproject.toml`).

3. Install dependencies into a fresh virtual environment:

   ```bash theme={null}
   python -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip setuptools
   pip install google-adk
   pip install orca-agent-engine
   ```

4. Add any helper libraries your agent needs (requests, domain SDKs, etc.) to `requirements.txt` or your packaging metadata so the runtime installs them alongside your agent code.

## Export the `root_agent`

The Orca runtime loads ADK projects by importing a module-level variable named `root_agent`. Define that agent with Google ADK's `Agent` class and list the tools or workflows it should expose.

```python theme={null}
from google.adk.agents import Agent
from google.adk.models import Gemini

# Optional: pull managed tools from the Orca execution context when you need MCP integration.
try:
    from orca.functions.agent_context import AgentContext
    managed_tools = AgentContext.current().get_tools()
except ImportError:  # Local unit tests can supply their own tools
    managed_tools = []

root_agent = Agent(
    name="multi_tool_agent",
    model=Gemini(model="gemini-2.5-pro"),
    description="Answer questions with live tool assistance.",
    instruction="Use available tools to fetch facts before responding.",
    tools=managed_tools,
)
```

Tips for adapting existing ADK samples:

* Keep fast feedback loops by writing thin wrapper functions around external systems (weather APIs, knowledge bases, etc.).
* Export the agent symbol through `__all__` in your package's `__init__.py` so the runtime can discover it.

## Package the project

Orca Engine accepts ADK artifacts packaged as ZIP archives.

### Package as a ZIP archive (recommended)

ZIP archives are the quickest way to bundle ADK agents. The structure mirrors the Python packaging pattern linked above.

```
multi_tool_agent/
  __init__.py
  agent.py
requirements.txt
```

```bash theme={null}
python -m pip freeze --exclude-editable > requirements.txt
zip -r multi_tool_agent.zip multi_tool_agent requirements.txt
```

* Run the `pip freeze` command from the same virtual environment you used while developing the agent so dependency versions stay in sync.
* The Orca runtime installs listed dependencies automatically when you deploy the agent.
* Reference the archive with `--agent-file multi_tool_agent.zip` during `snctl agents create` or `snctl agents update`.

## Deploy with `snctl`

Use the agent-aware subcommands to publish the package and configuration to StreamNative Cloud.

### Package as a ZIP archive

```bash theme={null}
snctl agents create \
  --tenant <tenant> \
  --namespace <namespace> \
  --name multi-tool-agent \
  --directory multi_tool_agent \
  --agent-framework adk \
  --session-mode SHARED \
  --inputs <input-topic> \
  --output <output-topic> \
  --agent-file multi_tool_agent.zip
```

* `--directory` matches the importable package path inside your ZIP archive.
* `--agent-file` accepts local files or URLs; point it to the ZIP archive you produced.
* Repeat the command with new artifacts or specs and `snctl agents update` to roll out changes. Use `snctl agents status` to monitor instances and `snctl agents trigger` to inject test messages.

## Next steps

* Configure [service accounts and permissions](/agent-engine/agents-setup) before deploying to production namespaces.
* Review managed tool configuration in the StreamNative Cloud Console so your ADK agent can discover MCP servers at runtime.
* Add automated tests that import the package and call `root_agent` to validate tools and prompts before publishing updates.