> ## 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 OpenAI Agents

> Build and package OpenAI Agents SDK projects for Orca Engine and deploy them with snctl.

This guide shows how to adapt projects built with the [OpenAI Agents Python SDK](https://openai.github.io/openai-agents-python/) so they run as Orca Agents on the StreamNative cloud platform. It walks through preparing a project, exposing the required `root_agent` entry point, packaging the code for upload, and deploying it with `snctl`.

## Prerequisites

* Python 3.10 or later with a virtual environment for isolating dependencies.
* The `openai-agents` library, the `openai` SDK components your agent requires, and any extra model integrations.
* The `orca-agent-engine` Python SDK for interacting with the Orca runtime.
* StreamNative CLI (`snctl`) installed and configured for the organization, tenant, and namespace where you plan to deploy.
* Access to StreamNative cloud topics that deliver agent input and capture responses.
* An OpenAI API key stored as a secret so the runtime injects it into the agent (for example, `OPENAI_API_KEY`).

## Prepare an OpenAI Agents project

1. Start from an OpenAI Agents SDK example, such as the multi-tool or Model Context Protocol (MCP) samples distributed with the Orca Engine examples, or create a new project from scratch.

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

3. Install dependencies inside a fresh virtual environment:

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

4. Add any helper libraries (HTTP clients, supporting SDK packages, etc.) to `requirements.txt` or your packaging metadata so they stay bundled with the agent artifact.

## Export the `root_agent`

The Orca runtime imports OpenAI projects by loading a module-level variable named `root_agent`. Define the agent with the OpenAI SDK and keep runtime secrets such as `OPENAI_API_KEY` outside the code.

```python theme={null}
from agents import Agent

root_agent = Agent(
    name="Assistant",
    instructions="You only respond in haikus.",
)
```

* Ensure your package exposes the module through `__all__` in `__init__.py` so the runtime can discover the agent.
* Validate the agent locally by importing the package and sending a sample request through the OpenAI SDK.

## Add tools and orchestrations

Use the `@function_tool` decorator to register functions as callable tools. This allows the agent to execute Python code when it needs to fetch data or perform actions.

```python theme={null}
from agents import Agent, function_tool

@function_tool
async def fetch_weather(city: str) -> str:
    # Replace with a real API call
    return "The weather is sunny."

root_agent = Agent(
    name="Assistant",
    instructions="Use tools when you need more context before answering.",
    tools=[fetch_weather],
)
```

* Leverage type hints and descriptive function comments to provide context that improves tool selection.
* When you need access to the execution context (for example, to stream tokens), annotate parameters with `RunContextWrapper` from the OpenAI SDK.

## Discover managed tools at runtime

When your Orca workspace provides managed tools through the console, fetch them with the Orca runtime context and supply them to the agent.

```python theme={null}
from agents import Agent
from orca.functions.agent_context import AgentContext

managed_tools = AgentContext.current().get_tools()

root_agent = Agent(
    name="operations_assistant",
    instructions="Use the managed tools provided by Orca Engine before you respond.",
    tools=managed_tools,
)
```

Wrap the context lookup in a `try`/`except` block if you run unit tests outside of Orca Engine.

## Package the project

Orca Engine accepts OpenAI agent artifacts packaged as ZIP archives.

### Package as a ZIP archive (recommended)

ZIP archives offer the fastest iteration loop. Organize the files so the top-level folder matches your importable module.

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

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

* Run `pip freeze` from the virtual environment you used during development so dependency versions stay consistent.
* The runtime installs listed dependencies automatically during deployment.
* Reference the ZIP archive with `--agent-file openai_multi_tool.zip` when running `snctl` commands.

## Deploy with `snctl`

Use the agent-focused commands to publish both the code and its configuration to the StreamNative cloud platform. The CLI captures all required settings, so you don't need to ship an `agent.yaml` file.

### Package as a ZIP archive

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

* `--directory` must match the importable package path inside your ZIP archive.
* `--agent-framework openai` tells Orca Engine to load the OpenAI runtime adapter.
* Repeat the command with updated artifacts or specifications and `snctl agents update` to roll out changes. Use `snctl agents status` to monitor runtime health and `snctl agents trigger` to submit test payloads.

## Next steps

* Configure [service accounts and permissions](/agent-engine/agents-setup) before deploying to production namespaces.
* Store the OpenAI API key and other credentials in StreamNative cloud secrets so the runtime injects them securely.
* Run local or CI tests that import the package and call `root_agent` to verify tool wiring before publishing updates.
* Use the StreamNative cloud console to review managed tool assignments and ensure your OpenAI agent can discover required Model Context Protocol (MCP) integrations.