Skip to main content
A useful agent does one job, has only the tools that job needs, and leaves its result somewhere your application can read. The recipes in this section each build one such agent end to end. Copy the one closest to what you need and change the instructions. If you have not run an agent yet, start with the quickstart. It explains the client setup every recipe uses.

​
Pick a recipe

​
Design an agent in five decisions

​
1. Name the one job

Write the job as a sentence a teammate would understand: “Answer order questions using our order system.” If you need the word “and” twice, you probably want two agents. A narrow agent is easier to instruct, test, and trust.

​
2. Decide where the work happens

A session without a sandbox uses no machine time. Only add one when the agent must run commands or handle files.

​
3. Give it the fewest tools that work

Every tool is something the model can misuse or call at the wrong time. Prefer narrow tools: lookup_order(order_id) rather than run_sql(query). Validate every argument in your code. Instructions such as “never refund more than $50” are guidance for the model, not a security control. See keep it safe.

​
4. Write instructions for the model, not for people

Good instructions say:
  • What the job is, in one or two sentences.
  • How to use each tool, and when not to.
  • What to do when information is missing: ask, or say it is unknown. Tell it not to guess.
  • What the result looks like: the format, the length, and the path for files (/workspace/outputs/report.md).
Keep procedures that are long, or that several agents share, in a skill rather than in the instructions.

​
5. Decide where the result goes

  • A reply. Read it from the session’s items, or stream it as it is written.
  • A file. Tell the agent to save it under /workspace/outputs. Orca saves it as an artifact when the turn completes.
  • An action in your system. Have the agent call a function tool, and let your code decide whether to carry it out.

​
Shared setup

Every recipe uses the same three settings as the quickstart:
Every recipe has a Python and a TypeScript program. Install the client versions the quickstart pins:
The TypeScript programs use top-level await, so they need "type": "module" in package.json, and Node 22.18+ or 24+ to run .ts files directly.
The recipes create real agents and sessions and call paid models. Recipes with a managed sandbox also use machine time and need your plan’s minimum balance of Orca credit in your wallet. Delete what you no longer need.

​
Before you ship an agent

  • Test it with bad input. Missing IDs, a file in the wrong format, a question outside its job. Check that it says so instead of inventing an answer.
  • Handle every turn outcome. A turn can end completed, failed, or cancelled. See turns and statuses.
  • Watch the cost. Check token usage on a few real runs before you scale up. Subagents and web searches add calls. See usage and wallet.
  • Share it. When it works, a kit hands the agent, its skills, and its templates to a teammate or customer as one link.