Skip to main content
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 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: 
    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. 
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. 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

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

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 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.
⌘I