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-pythonlibrary and any model SDKs your agent requires. - The
orca-agent-enginepython 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
- Start from an ADK reference implementation. You can reuse examples from the Google ADK samples repository or the Orca engine examples provided below.
-
Copy the project into your own source repository and update the package metadata (for example, rename the module and adjust
pyproject.toml). -
Install dependencies into a fresh virtual environment:
-
Add any helper libraries your agent needs (requests, domain SDKs, etc.) to
requirements.txtor 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.
- 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__.pyso 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.- Run the
pip freezecommand 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.zipduringsnctl agents createorsnctl agents update.
Deploy with snctl
Use the agent-aware subcommands to publish the package and configuration to StreamNative Cloud.
Package as a ZIP archive
--directorymatches the importable package path inside your ZIP archive.--agent-fileaccepts local files or URLs; point it to the ZIP archive you produced.- Repeat the command with new artifacts or specs and
snctl agents updateto roll out changes. Usesnctl agents statusto monitor instances andsnctl agents triggerto 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_agentto validate tools and prompts before publishing updates.