# Building with agents — the developer's guide

> Where a developer starts with agents in an Osy# app. Decide what you are building, read the smallest working app for that shape, see which kit gives you what, follow one piece of work through all of them, and look choices up in tables. Every example in the guide is a whole app that is compiled and run by the docs gate.

<!-- id: agent-guide · area: agent · stability: preview · html: https://osysharp.com/reference/agent/guide/ -->

> **You are here:** [Agents in an Osy# app](https://osysharp.com/reference/agent/overview/) › Building with agents

## Summary        {#summary}
This guide is written from the app outward. It does not start with the kits. It starts with what you want the app
to do, and tells you which kits that takes and what you have to decide.

If you are not a developer, or you want to see what all this looks like to the people who use it, start one level
up: [Agents in an Osy# app — what they are, in plain words](https://osysharp.com/reference/agent/overview/).

## Description    {#description}

### Where do I start?   {#start}

| If you want to | Read |
|---|---|
| know what kind of app you are building | [Deciding what to build — four shapes of app with agents in it](https://osysharp.com/reference/agent/guide-deciding/) — four shapes, and how to tell which is yours |
| write your first agent | [Shape 1 — an assistant for one person](https://osysharp.com/reference/agent/guide-assistant/) — the smallest working app |
| know what you must decide, and what holds if you decide nothing | [The six decisions — what you say about an agent, and what holds if you say nothing](https://osysharp.com/reference/agent/guide-decisions/) — six decisions |
| see how the kits fit together | [The map of the kits — which sits on which, and what each one is for](https://osysharp.com/reference/agent/guide-kits/) — one map, and a page for each kit |
| follow one piece of work through all of it | [One piece of work, followed end to end](https://osysharp.com/reference/agent/guide-work-end-to-end/) — thirteen hops, with the code for each |
| choose between two ways of doing something | [Choosing — I want X, so use Y, not Z, because](https://osysharp.com/reference/agent/guide-choosing/) — "I want X: use Y, not Z, because" |
| look a word up | [Glossary — the words the Agents guide uses](https://osysharp.com/reference/agent/guide-glossary/) |

### What are the four shapes?   {#shapes}
Each page has a whole app that runs. Each app is the one before it, grown.

1. [An assistant for one person](https://osysharp.com/reference/agent/guide-assistant/) — somebody asks, the agent does a typed job, the answer
   comes straight back.
2. [Work for people, with approvals](https://osysharp.com/reference/agent/guide-approvals/) — the agent proposes what it may not do alone; a
   person approves in their inbox.
3. [Agents inside a business process](https://osysharp.com/reference/agent/guide-process/) — the agent's work is a step of a process that runs
   for days.
4. [A team with a coordinator](https://osysharp.com/reference/agent/guide-team/) — one agent hands typed pieces to specialists.

### What is true of every example here?   {#examples}
- It is a **whole app**, from its first line to its tests. Copy it into a project and it compiles.
- It is **run**, not only compiled: the docs gate runs each example's tests on every change.
- Its model is a [[agent-guide-glossary#scripted-model|scripted model]], so it costs nothing and needs no key. In a
  real app that one line names a provider instead: see [Osysharp.Models.Anthropic — Anthropic's models as a provider](https://osysharp.com/reference/agent/kit-anthropic/), [Osysharp.Models.OpenAi — OpenAI's models, and anything that speaks the same wire, as a provider](https://osysharp.com/reference/agent/kit-openai/),
  [Osysharp.Models.Gemini — Google's Gemini models as a provider](https://osysharp.com/reference/agent/kit-gemini/).
- It is about a small translation bureau. The domain is the same across the four shapes so you can see what each
  shape adds.

### How is the guide laid out?   {#layout}
Two layers. The first is for anybody and has no code: [what agents in an app are](https://osysharp.com/reference/agent/overview/),
[what you can build](https://osysharp.com/reference/agent/overview-what-you-can-build/), [what a person sees](https://osysharp.com/reference/agent/overview-what-people-see/),
[what stays under people's control](https://osysharp.com/reference/agent/overview-control/), three processes told as stories, and
[what release 1 does not include](https://osysharp.com/reference/agent/overview-not-included/). The second is this one.

Under both is the reference: one page for each concept, with every setting and every function. Each guide page ends
with "Go deeper", which links to the reference pages behind it. [Agents (a class with a job, its own account, a budget and a record)](https://osysharp.com/reference/agent/index/) lists them all.

## What to read next   {#read-next}
- [Deciding what to build — four shapes of app with agents in it](https://osysharp.com/reference/agent/guide-deciding/) — the four shapes, and how to tell which is yours
- [Shape 1 — an assistant for one person](https://osysharp.com/reference/agent/guide-assistant/) — the smallest app with an agent in it
- [The map of the kits — which sits on which, and what each one is for](https://osysharp.com/reference/agent/guide-kits/) — the map of the kits

## Go deeper   {#see-also}
- [Agents (a class with a job, its own account, a budget and a record)](https://osysharp.com/reference/agent/index/) — the reference pages about agents, by subject
- [Writing an agent — a class with a purpose, skills and an account of its own (Agents kit)](https://osysharp.com/reference/agent/agents/) — the agent class
- [The Llm kit — call a model, and know what each call cost](https://osysharp.com/reference/agent/llm-calls/) — the model calls underneath
- [Workflows (the run that outlives the request)](https://osysharp.com/reference/workflow/index/) — workflows, which processes are made of