Agent: what the AI is
An agent is a saved configuration. It says which model to use, what instructions to follow, and which tools the model may call. Creating an agent does not run anything or call the model. Create an agent once and reuse it for many conversations. Each session copies the agent’s settings when it is created, so if you edit the agent later, only sessions created after the edit use the new settings.Session: one conversation
A session is one conversation with an agent. It remembers everything said so far, so a follow-up message can refer to earlier ones. A session also decides:- Whether the agent gets a sandbox, through its
environment. A sandbox is called an environment in the API. - Which stored credentials the agent’s tools may use, through
vault_ids.
Turn: one round of work
A turn is everything the agent does in response to one message. Inside a turn, the agent may call the model several times, run tools, read results, and call the model again, until it has a final answer. You do not drive this loop; Orca does. Every turn ends in one of three ways:completed, failed, or cancelled. A session can contain many turns, one after another. Only one turn runs at a time.
Creating a session or sending a message returns immediately, before the turn finishes. Your request was accepted, nothing more. To know the outcome, wait for the turn to end: either stream events or poll the turn list. Turns and statuses covers this in detail; it is the most common source of confusion for new users.
Items: the saved history
An item is one entry in the conversation history. The history is not only chat messages; it records everything the agent did:
Read items with
sessions.items.list(session_id). The list is paginated and newest first.
Events: the live view
Events are the same activity, delivered as it happens over a server-sent events (SSE) stream: text as it is generated, items as they are added, and status changes. Use events to show progress in a UI. Use items and turns when you need the saved record. Events also go the other way: you send a follow-up message, a tool result, or a cancel request by posting an input event to the session. See streaming and cancellation.Environment: the sandbox
An environment is the machine where the agent runs shell commands and reads and writes files. Every session picks one of three types when it is created:
Each session has its own environment; sessions never share one. See execution environments.
Artifacts: files the agent produced
When a turn completes, Orca collects every file the agent wrote under theoutputs folder of its workspace (/workspace/outputs in a managed sandbox) and saves a copy as an artifact. Artifacts are snapshots: if the agent changes the file in a later turn, the earlier artifact stays the same, and the later turn gets its own.
Download artifacts before you delete the session. Deleting a session deletes its artifacts. See files and artifacts.
Where each piece runs
This matters for security and debugging, because it tells you which machine makes each network request.Supporting resources
These are created separately and then attached to agents or sessions:What you are responsible for
- Waiting for the real outcome. An accepted request is not a finished turn. See turns and statuses.
- Answering function calls. If your agent has function tools, your application must return results or the turn waits.
- Deciding what is safe. Tool arguments come from the model. Validate them in your code; do not rely on instructions to prevent dangerous actions.
- Cleaning up. Delete sessions you no longer need. This releases their sandbox. Agents, files, skills, templates, and vaults are deleted separately.
Next
Turns and statuses
How to tell when work is done, and what to do when it is not.
Quickstart
See every piece in one short program.