You are here: Building with agents › Choosing
Summary#
Find the row that says what you want. Each one names what to use, what to leave, and the reason in a sentence. Every "use" is a link to the page that shows it working.
Description#
Do I need an agent, a model call, or a workflow step?#
| I want | Use | Not | Because |
|---|---|---|---|
| one answer from a model: a summary, a draft, a translation | [[agent-llm-calls|Llm.Complete]] | an agent | nothing has to be looked up or changed, so there is nothing for an agent's account, gate or record to do. The call is still routed, limited and metered. |
| fields read out of a text, or one decision among a few | [[agent-llm-typed-answers|Llm.Extract<T> · Llm.Decide<T>]] | an agent | the answer is typed and checked against its class already |
| the model to look things up in my app, or change something in it | an [[agent-agents|agent]] with a [[agent-skills|skill]] | a model call with my own loop around it | tools then run as an account with rights, under a gate, within a limit, on a record |
| the same steps every time, with no judgement in them | a plain function or a [[workflow-index|workflow]] | an agent | it is cheaper, exact, and needs no model |
| steps over several days, with people between them, and judgement in one or two of them | a workflow with an [[agent-processes|agent step]] | one long agent job | the process owns the order and the waiting; the agent does only the step that needs judgement |
| a conversation with a person | [[agent-ask#ask|Ask or Stream]] on an agent | Do | the answer is words, not a typed result |
Should it act alone, propose, or get a standing rule?#
| The tool | Use | Not | Because |
|---|---|---|---|
| only reads | nothing: it runs alone | — | a tool marked Query is never proposed |
| changes the app's own data, and a person reads the result anyway | Alone, or [[agent-autonomy#gate|Permits.ChangesAlone()]] | proposing each one | an approval nobody ever refuses teaches people to press yes |
| sends something, spends money, or reaches outside the app | [[agent-autonomy#proposal|propose]] — the default | Permits.Everything() | it cannot be taken back, and a person's yes runs it with that person's rights |
| must be seen by a person every single time | ProposeEveryTime | a standing rule | a tool listed there takes no "from now on, alone" |
| must never be done by this agent | Never | trusting the instructions | the tool is not offered to the model at all, and cannot be approved |
| is approved again and again by the same person | a [[agent-autonomy#standing|standing rule]] | changing the code | it covers only the work done for the person who gave it, counts its own use, and can be taken back |
| belongs to another department | a skill's [[agent-autonomy#route|DecidedBy]], to a restricted queue | the default | the person who asked then cannot approve it themselves |
Is this an assignment or a process?#
| The work | Use | Not | Because |
|---|---|---|---|
| has the same steps each time, known in advance | a [[agent-processes|process]] | an assignment | the steps are the point: they can be drawn, timed and followed |
| has a known outcome and an unknown way there | an [[agent-assignments|assignment]] | a process | it is done when its criteria are met, not when everything attached to it has finished |
| may come back after it was closed | an [[agent-assignments#reopen|assignment]] | a new process run | it reopens and keeps everything it had |
| is one question or one approval | a [[agent-human-requests|request]] | either | a request is answered once and is done |
| gathers evidence, letters and findings as it goes | an assignment with a [[agent-work-repositories|work repository]] | lines in a log | each item keeps who added it, from where, and every version |
The two combine. An assignment can have agent work, requests and a process attached to it; any of them can fail or be replaced and the assignment stays. See [[agent-assignments#work]].
One agent with more tools, or delegation?#
| The job | Use | Not | Because |
|---|---|---|---|
| is small, and needs one set of rights | one agent, more tools | delegation | every piece handed on is a piece of work of its own, with its own model calls |
| has parts that need different rights | [[agent-delegation|delegation]] | one agent with every role | a specialist acts with its own agent's roles, so no agent holds more than its part needs |
| has parts that can be done at the same time | delegation | one agent doing them in turn | pieces asked for in one turn run side by side |
| has a part that must not spend past a share | delegation with budget: | one limit for everything | a piece that runs out is stopped alone; the rest goes on |
| has parts that people correct separately | a skill each, or an agent each | one large skill | corrections and instructions are kept for each agent and skill |
Who approves: a queue or a person?#
| The decision | Use | Not | Because |
|---|---|---|---|
| is the asker's own to make | nothing: it goes to the person the work is for | a queue | their yes runs it with their own rights |
| is made in a process, where nobody is signed in | nothing: it goes to the agent's sponsor — or .For(person) on the step | a queue nobody watches | somebody always answers for an agent |
| belongs to a role with several holders | [[agent-autonomy#route|ProposalRoute.ToQueue("Finance")]], a restricted queue | the person who asked | whoever works that queue decides, and the asker is refused even when they work it too |
| belongs to exactly one office holder | ProposalRoute.ToPerson(account) | a queue of one | it is put to them by name |
| must not wait when that person is away | the policy [[agent-roles#deciders|DecidesAgentProposals]] | sharing an account | whoever it admits may decide a proposal put to somebody else |
A queue that is not restricted is worked by everybody who works the inbox. Restrict the queue a routed proposal goes to. See The WorkQueues kit — queues, who holds what, and the service levels promised on any item.
When does each Privacy kit arrive?#
You add Osysharp.Privacy when the app holds personal data and must answer a person who asks what is held, or asks to be erased. The four below are never written in a manifest: each arrives by itself when the app uses both kits it sits between.
| The app uses Privacy and | It gets | It covers | You write |
|---|---|---|---|
| [[agent-kit-agents|Agents]] | [[agent-kit-privacy-agents|Privacy.Agents]] | what agents did for a person and about a person | MarkAgentWorkAbout(task, subject) for work about somebody |
| [[agent-kit-llm|Llm]] | [[agent-kit-privacy-llm|Privacy.Llm]] | the model calls made for a person; the meter keeps no text | nothing |
| [[agent-kit-assignments|Assignments]] | [[agent-kit-privacy-assignments|Privacy.Assignments]] | the people on an assignment and the person it is about | MarkAssignmentAbout(a, subject) |
| [[agent-kit-work-repositories|WorkRepositories]] | [[agent-kit-privacy-work-repositories|Privacy.WorkRepositories]] | the items a piece of work keeps about a person, each kind for its own time | MarkItemAbout(item, subject) |
How do I test without a model?#
| I want to test | Use | Because |
|---|---|---|
| one model call | [[agent-llm-scripted-model|ScriptedModel and ScriptedAnswer.Stub]] | routing, limits and the meter are the real ones; only the provider is scripted |
| what an agent does | [[agent-testing|AgentScript.Of(Says.Tool(…), Says.HandBack(…))]], then Trajectory.Of(task) | the script says what the model answers turn by turn; the test reads back what the agent then did |
| several agents at once | [[agent-testing#cast|AgentCast]] | each agent gets its own script; Trajectory.Tree reads the tree back |
| a whole process | [[agent-testing#process|ProcessTrail]] | which skills ran, in which states, how each ended, what it cost |
| a person's answer | runas (Person) { ApproveAgentProposal(…) } or AnswerRequest(…) | the yes runs as that person, exactly as on screen |
| a wait of days | TestClock.Advance(TimeSpan.FromDays(3)) | nothing sleeps; the test asserts no model was asked meanwhile |
| a provider that is down | throw ExternalServiceException from the script | fallback, retries and the failure branch are then real |
None of it costs anything or needs a key. Every example in this guide is tested this way.
What to read next#
- The six decisions — what you say about an agent, and what holds if you say nothing — the six decisions these tables belong to
- The map of the kits — which sits on which, and what each one is for — the kits named in the tables, on one map
- Glossary — the words the Agents guide uses — every term used here
Go deeper#
- What an agent does alone, what it proposes, what it never does — the gate and proposals (Agents kit) — the gate, proposals, routing, standing rules
- An agent hands work on to other agents — at once, typed, and never with more than it holds (Agents kit) — handing work on
- Assignments — a piece of work owned until its outcome is reached (Assignments kit) — a piece of work owned until its outcome is reached
- Agents in business processes — an agent's work as a step of a workflow, told on the run (Agents.Processes kit) — an agent's work as a step of a process
- Privacy for the agent family — agents, the model meter, assignments and work repositories under a person's request — the four holders, and what an erasure leaves
- Testing an agent without a model — Says, AgentScript and Trajectory (Agents.Testing kit) — scripting the model