Quickstart
Deploy your first agent on Orca Agent Engine end-to-end - create an environment, define an agent, and run a session.
This quickstart walks you from an empty Workspace to a running agent session that responds to a user message. You will:
- Look up your registry endpoint.
- Create an environment.
- Define an agent.
- Start a session and send a message.
By the end you have an agent session processing a real event through the registry API.
Prerequisites
- A running self-hosted Agent Engine deployment and its registry endpoint.
For a local Compose deployment with a Workspace API key, follow the ork local tutorial. It uses x-api-key authentication and includes CLI, API, TypeScript, and Python examples. The Bearer-token cURL examples below require an OIDC token instead.
1. Get your registry endpoint
Every Agent Engine API call targets your deployment's registry endpoint.
Registry endpoint
Examples on this page target your registry endpoint - the deployment host root, with no path
suffix. For CLI, set ORCA_REGISTRY_URL and exactly one of ORCA_ACCESS_TOKEN (Bearer) or
ORCA_API_KEY (x-api-key). For TypeScript SDK, set ORCA_BASE_URL / ORCA_API_KEY (Bearer).
To find the endpoint, see Connect to the registry.
Model access is configured for you, not through the registry API. On StreamNative Cloud an operator declares the Workspace's LLM endpoints as model providers, which the API exposes read-only. On a self-hosted deployment the model endpoint and its credential are set on the harness at deploy time. Either way there is nothing to create here - agents just name a model. See Model access.
2. Create an environment
An environment is the container template that hosts your sessions.
environment=$(ork agent environments create --name "quickstart-env" -o json)
ENV_ID=$(jq -r '.id' <<< "$environment")3. Define an agent
agent=$(ork agent create \
--name "quickstart-agent" \
--model claude-sonnet-4-6 \
--system "You are a helpful coding assistant." \
-o json)
AGENT_ID=$(jq -r '.id' <<< "$agent")For full agent configuration options (tools, MCP servers, skills), see Define agents.
4. Start a session and send a message
session=$(ork agent sessions create \
--agent "$AGENT_ID" \
--environment-id "$ENV_ID" \
-o json)
SESSION_ID=$(jq -r '.id' <<< "$session")
ork agent sessions events send message \
--session "$SESSION_ID" \
--text "Write a Python function that prints Fibonacci numbers."Stream the response:
ork agent sessions events stream --session "$SESSION_ID"For full event-handling details, see Events and streaming.
Where to go next
Define agents
Version an agent's model, system prompt, tools, and skills.
Triggers
Run an agent continuously on a schedule or in response to events.
Tools
Give an agent the built-in sandbox toolset, MCP servers, or your own custom tools.
Architecture
Understand the runtime and registry pillars.
Every path here is a core API path, served by any deployment. See the Registry API reference for the full set, and How the API is organized for the difference between core operations and the extension groups a particular deployment adds.