# Osysharp.Agents — an agent given a real job inside an app, and trusted with it

> `Osysharp.Agents` is the core: an agent is a class with an account of its own, a skill is a typed job whose tools are the app's own functions, and every piece of work has a hard limit, a receipt and a record of each step.

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

> **You are here:** [Building with agents](https://osysharp.com/reference/agent/guide/) › [The kits](https://osysharp.com/reference/agent/guide-kits/) › Agents

## Summary        {#summary}
`Osysharp.Agents` is the core: an agent is a class with an account of its own, a skill is a typed job whose tools are the app's own functions, and every piece of work has a hard limit, a receipt and a record of each step.

It also holds everything about who is in charge: what an agent does alone and what it proposes, asking a person and waiting, consulting a stronger model, handing typed pieces to other agents, and people correcting its work. None of that needs another kit. The other kits put it on screens and connect it to inboxes, processes and assignments.

|  |  |
|---|---|
| Package | `Osysharp.Agents`, version 1.7.0 |
| You add it with | `use Osysharp.Agents;` in the app's manifest. |
| It sits on | [[agent-kit-llm\|Llm]] |
| It also uses | `Identity`, `Workflow` — parts of the platform's own library |
| Bridges that arrive when it meets another kit | [[agent-kit-agents-human-requests\|Agents.HumanRequests]], [[agent-kit-agents-processes\|Agents.Processes]], [[agent-kit-assignments-agents\|Assignments.Agents]], [[agent-kit-privacy-agents\|Privacy.Agents]], [[agent-kit-work-repositories-agents\|WorkRepositories.Agents]] |
| Its own test app | A packhouse where fruit arrives by the crate and an inspector grades it — `kits/agents/tests` |

## Description    {#description}

### What do you get without writing anything?   {#free}
- An agent that says nothing only looks things up; every change is proposed to a person.
- It never does for a person what that person may not do themselves.
- A hard limit on every piece of work. Work that runs out is stopped and keeps what it did.
- A receipt for every piece of work and a chained record of every step.
- Work that waits for a person costs nothing and goes on from the same point, days later.
- An instruction reaches an agent only after a person has made it active.

### When do you need it?   {#when}
Every shape. [Shape 1](https://osysharp.com/reference/agent/guide-assistant/) is this kit and [Llm](https://osysharp.com/reference/agent/kit-llm/) alone; [shape 4](https://osysharp.com/reference/agent/guide-team/) adds nothing to it.

### What does it expose?   {#exposes}
The tables below are generated from the kit itself, not written by hand: `osy kits Osysharp.Agents --surface` lists each of
them with the code of the kit's own test app that uses it, and the tests that show it working.

**Settings** — one line in the app, each field with a default.

| You write | It says |
|---|---|
| `app.AgentTeaching = new TeachingSetup { MostInstructions, MostCharacters, DraftsWith }` | How this app teaches its agents. |
| `app.Agents = new AgentsSetup { Agents, TaskBudget, MaxTurns, Guards, AbandonedAfter, AbandonedCheckEvery }` | How this app uses agents. |

**Types you derive from** — your app writes a class of its own.

| Type | What it is |
|---|---|
| `Agent` | An agent: a principal of the app with a purpose, the skills it holds, and what it may spend. |
| `AgentGuard` | A guard: a class of the app's that is asked at four points of every piece of work, and may stop the step. |
| `Skill` | A job with a typed input and a typed result. |

**Policies you answer** — each is a question the kit asks your app: `policy Name => …;`

| Policy | The question | Until the app says otherwise |
|---|---|---|
| `ErasesAgentRecords` | Who may erase what an agent's record said, take a person off it, and delete work whose time is up. | nobody |
| `WidensAgentAutonomy` | Who may tell an agent "from now on, do this alone" — a standing rule for the work it does for them — and take it back. | nobody |
| `TeachesAgents` | Who teaches the agents: reads what is proposed, makes an instruction active, retires one, and puts an agent back to an earlier instruction set. | nobody |
| `SponsorsAgents` | Who names the person accountable for an agent (`SponsorAgent`). | whoever supervises |
| `PausesAgents` | Who pauses an agent and lets it work again (`PauseAgent`, `ResumeAgent`). | whoever supervises |
| `ReadsAllAgentWork` | Who reads the receipt of every piece of work, whoever it was for: which agent and skill, for whom, where it stands, when, and what it cost. | whoever supervises or audits |
| `ReadsAgentWorkOf` | Who reads the receipts of work charged to particular scopes — a piece of work at a time, by what its caller charged it to (`AgentTask.ChargedTo`, one scope a line: `Agents.Of<T>().On("report:" + … | nobody |
| `DecidesAgentProposals` | Who decides a proposal that was not put to them. | whoever supervises |
| `UsesAgents` | Who gives agents work and reads the runs they asked for. | nobody |
| `SupervisesAgents` | Who is in charge of the agents: names each one's sponsor, pauses and stops them, and reads every run's record. | nobody |
| `AuditsAgents` | Who reads every run WITH its content — the prompts, what each tool was given and what it answered. | nobody |
| `AgentsMayConsult` | Whether an agent that names a model to consult may ask it. | everybody |
| `DirectsAgentsForOthers` | Who may give an agent work for somebody else (`Agents.Of<X>().For(person)`) while signed in themselves. | nobody |

**Functions you call**, those its own tests show most first.

| Function | What it does | Tests that show it |
|---|---|---|
| `ProposeAgentInstruction(InstructionDraft draft)` | Propose an instruction. | 154 |
| `Answered(AgentRun run, LlmResponse response, string model, string routeRule, Guid? call, long costMicros, int attempts)` | The model answered: its message joins the conversation, the call joins the record and the receipt. | 154 |
| `Words(string name)` | A class's name as words: "GradeCrate" → "Grade crate". | 154 |
| `SponsorAgent(string agent, Principal sponsor)` | Name the person accountable for an agent — `SponsorAgent(Agents.Of<Auditor>().Name, lead)`. | 154 |
| `PauseAgent(string agent, string why = …)` | Pause an agent: it takes no new work until `ResumeAgent`. | 154 |
| `ResumeAgent(string agent, string why = …)` | Let a paused agent take work again. | 154 |
| `BareName(string fullName)` | A class's own name, without its namespace. | 154 |
| `ForgetAgentWork(AgentTask task)` | Delete a piece of work whose time is up: the receipt of `task`, of the work it is part of and of everything under it, every line of the record and every request for help. | 146 |
| `ReviseAgentInstruction(AgentInstruction instruction, string guidance, string why)` | Change the words of an instruction that is still proposed — what a reviewer does before making it active. | 146 |
| `ActivateAgentInstruction(AgentInstruction instruction, string why = …)` | Make an instruction active. | 146 |
| `RejectAgentInstruction(AgentInstruction instruction, string why)` | Say no to a proposed instruction, with the reason. | 146 |
| `RetireAgentInstruction(AgentInstruction instruction, string why)` | Take an instruction out of use. | 146 |
| `RollBackAgentInstructions(string agent, int toSet, string why, string skill = …)` | Put an agent back to an earlier instruction set: what was active then is active again, and what has been made active since is retired. | 146 |
| `EraseAgentInstruction(AgentInstruction instruction, string why)` | Erase what an instruction said, and whose work it was for. | 146 |
| `WithholdAgentInstruction(AgentInstruction instruction, string why)` | Take an active instruction out of use without a teacher — for a privacy request that keeps what is held about a person out of use: an instruction for their work is their data, and the agent stops b… | 146 |
| `ForgetWhoTaughtAgents(Principal person)` | Take a person off what they taught: the corrections they wrote, the instructions they proposed, read, activated or retired, and the instruction sets they made no longer say who. | 146 |
| `EraseAgentWorkContent(AgentTask task, string why)` | Erase what a piece of work said: the content of every line of its record (what the agent was shown, what each tool was given and answered, what the model said), what was asked and answered when i… | 143 |
| `AnonymiseAgentWork(AgentTask task, string why)` | Take the person off a piece of work: who it was for and who gave it, what it was about, how it ended in words, and every line's sentence — for the whole of the work `task` is part of. | 143 |
| `StopAgentTask(AgentTask task, string why = …)` | Call a piece of work off: it stops at its next step, as `Cancelled`, and keeps what it has done and spent. | 143 |
| `CorrectAgentWork(AgentTask task, Correction correction)` | Correct a piece of work: what was wrong, what right looks like, and why — on the result, on one step of the record (`Step`), or on something it proposed (`Proposal`). | 142 |
| `WithdrawAgentCorrection(AgentCorrection correction, string why)` | Take a correction back — it was itself mistaken. | 142 |
| `EraseAgentCorrection(AgentCorrection correction, string why)` | Erase what a correction said: what was wrong, what right looks like, why, the right result and the step's own words. | 142 |
| `ForgetWhoOversawAgents(Principal person)` | Take a person off how they oversaw the agents: the standing rules they gave or took back, the changes they made to an agent's place and the times they were named its sponsor, the questions agents… | 142 |
| `InstructionSetOf(string agent)` | The number of the set an agent is on: 0 when nobody has taught it anything. | 137 |
| `InstructionSetNumbered(string agent, int number)` | One set of an agent, by its number. | 137 |
| `AllowAlone(string agent, ActionInfo tool, string skill = …, bool forEverybody = …, Guid? fromProposal = …)` | From now on, alone: let an agent run one of its tools without proposing it, for the work it does for whoever says so. | 124 |
| `RevokeStandingRule(AgentStandingRule rule, string why = …)` | Take a standing rule back: the agent proposes that tool again from its next step. | 124 |
| `TraceOf(AgentTask task)` | The record of the work `task` belongs to — every line of its chain, in order — as plain values. | 34 |
| `CheckChain(List<TraceLine> lines)` | The same check, over lines held as values — a record that was exported, or read some other way. | 33 |
| `VerifyTrace(AgentTask task)` | Check a record: recompute the chain of the work `task` belongs to and say whether every line is as it was written — none changed, none removed, none slipped in. | 29 |
| `InstructionSetHashNow(string agent)` | The hash of the set an agent is on now. | 19 |
| `ProposalFingerprintNow(AgentProposal proposal)` | What a proposal's fingerprint is NOW: the same sum over the skill as it stands, the subject as it stands and the instruction set the agent is on. | 19 |
| `RouteWords(AgentProposal proposal)` | Where a proposal was put, as a person reads it: "Ada", "the Finance queue". | 19 |
| `ApproveAgentProposal(AgentProposal proposal, bool alwaysLikeThis = …)` | Say yes to a proposal. | 17 |
| `AnswerAgentQuestion(AgentHelp question, string answer)` | Answer a question an agent put to you. | 7 |
| `RejectAgentProposal(AgentProposal proposal, string reason)` | Say no, with the reason — which the agent is given, and goes on from. | 4 |
| `ProposalsForMe()` | The proposals waiting for whoever is signed in. | 4 |
| `AgentName(string fullName)` | What people call an agent — what every screen and every sentence a person reads says, in place of its class's name: the `DisplayName` its class gives it, or the class's own name in words (`Insura… | 4 |
| `CloseAbandonedAgentWork()` | Close the work nothing is doing any more. | 3 |
| `InstructionSetsOf(string agent)` | An agent's instruction sets, newest first: every change to what it is told, with who, when and why. | 3 |
| `WasAbandoned(AgentTask task)` | Whether a piece of work was abandoned: it says it is under way, and nothing has been written on the record of the whole it belongs to for `AgentsSetup.AbandonedAfter` — whatever was doing it is g… | 2 |
| `RetryAgentWork(AgentTask task)` | Try a piece of work again: the same agent, the same skill, the same brief — started from the beginning, on a receipt of its own that says which attempt it follows (`RetryOf`, `Attempt`), for the … | 2 |
| `CorrectionsOfAgent(string agent, string skill = …)` | The corrections made of an agent's work that still count — not taken back — newest first. | 2 |
| `InstructionsOf(AgentTask task)` | What a piece of work ran with: the instruction set it started under, each instruction it was sent, and — so a past result can be explained — what the agent is told now that this work had not been… | 2 |
| `SourcesOf(AgentInstruction instruction)` | The corrections an instruction was drawn from, oldest first. | 2 |
| `InputFieldsOf(SkillBase skill)` | What a form asks for to run `skill` on demand — one field for each member of what it takes, as it is handed work (`SkillBase.HandedSchema()`): a skill that takes a row asks for its id, one that t… | 2 |
| `InputJsonOf(List<SkillInputField> fields, Dictionary<string, string> values)` | What a form's answers are as the JSON the skill takes — `values` by field name ("" for a skill that takes one value). | 2 |
| `RunSkill(string agent, string skill, string inputJson, string about = …)` | Run a skill on demand: `agent` does `skill` with `inputJson` — what the skill takes, as `InputFieldsOf` asks for it — for whoever is signed in, as any piece of work they give it. | 2 |
| `QuestionsForMe()` | The questions waiting for whoever is signed in. | 2 |
| `SeatChangesOf(string agent)` | Every change to an agent's place, newest first. | 2 |
| `CorrectionsOf(AgentTask task)` | The corrections made on a piece of work, oldest first — those whoever is reading may see. | 1 |
| `WhatWaitsOnThem(Principal person)` | What still waits on a person before they can be taken off how they oversaw the agents — a question an agent put to them, a proposal sent to them, an agent they sponsor now — in words; "" when nothi… | 1 |
| `DraftAgentInstruction(List<AgentCorrection> corrections, Guid? forPerson = …, string onScope = …)` | Have a model word an instruction from one or several corrections of the same agent's work: it is asked for the one rule they have in common, and what it answers is proposed — exactly as if a pers… | 1 |
| `EffectOf(AgentInstruction instruction)` | Whether an instruction helped, counted — no model is asked. | 1 |
| `InstructionsOfAgent(string agent)` | An agent's instructions — every one whoever is looking may read — newest first. | 1 |
| `RelayProposalDecision(AgentProposal proposal, bool approved, string reason, Principal? by)` | A decision a person made somewhere else — on a request in their inbox — carried to the proposal by the code that received it. | 1 |
| `ArgumentsInWords(string argumentsJson)` | A json object's members as a person reads them — "crate: C-104 · flag: short" — for a list or a line of a record. | 1 |

**Events your app can hear** — `[On] void Heard(EventName e) { … }`

| Event | When |
|---|---|
| `AgentWorkCorrected` | A piece of an agent's work was corrected. |
| `AgentWorkErased` | What an agent's work said was erased, or whose it was taken off it. |
| `AgentTaskStarted` | An agent was given a piece of work. |
| `AgentTaskFinished` | A piece of work finished, and handed back what its skill promises. |
| `AgentTaskFailed` | A piece of work could not be finished. |
| `AgentTaskStopped` | A piece of work was stopped before it finished: its turns or its money ran out, or somebody called it off. |
| `AgentAskedForHelp` | An agent asked for help — of a more capable model, or of a person. |
| `AgentWorkGaveUp` | A piece of work failed for good: its last attempt did. |
| `AgentTaskWaiting` | A piece of work stopped on a person, and goes on when they have decided or answered. |
| `AgentWorkNoLongerAwaited` | The run that was waiting for a piece of work was stopped, or moved on without it: nobody will read what the work hands back. |
| `AgentProposed` | An agent proposed something it may not do alone: a person decides. |
| `AgentProposalDecided` | A proposal was decided — approved and run, rejected, or found out of date. |
| `AgentQuestionClosed` | A question an agent put to a person has its answer — or will get none. |
| `AgentInstructionProposed` | An instruction was proposed. |
| `AgentInstructionsChanged` | What an agent is told changed: an instruction was made active or retired, or the agent was put back to an earlier set. |
| `AgentSeatChanged` | An agent's place changed: it was paused or resumed, or its sponsor was named. |

**Records your app grants access to** — the kit writes them; `partial entity X { security { … } }` says who else reads them.

| Record | What it is |
|---|---|
| `TraceEvent` | One line of the record. |
| `AgentProposal` | One proposal: the tool an agent wants to run, with the arguments it would run it with — exactly — what running it does, why the agent wants to, and what it had looked at. |
| `AgentHelp` | One request for help: who was asked, why, what was asked with what context, what came back and what it cost. |
| `AgentStandingRule` | A standing rule: one tool an agent may run alone from now on, where its declaration says "propose" — said by a person after seeing what it proposes ("approve all like this"), and theirs to take b… |
| `AgentInstruction` | One instruction: what an agent is told, in the words it is sent, and why — for all its work, for one skill, for the work it does for one person, or for work charged to one thing (a team, a client). |
| `AgentInstructionSet` | One instruction set: everything an agent is told from one change to the next. |
| `AgentCorrection` | One correction: on which piece of work and which part of it, what was wrong, what right looks like, why — and who says so. |

## What to read next   {#read-next}
- [Shape 1 — an assistant for one person](https://osysharp.com/reference/agent/guide-assistant/) — Shape 1 — an assistant for one person
- [Osysharp.Agents.Testing — testing an agent without a model](https://osysharp.com/reference/agent/kit-agents-testing/) — testing an agent without a model
- [One piece of work, followed end to end](https://osysharp.com/reference/agent/guide-work-end-to-end/) — one piece of work, followed end to end

## Go deeper   {#see-also}
- [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, its account, who is in charge
- [A skill — a typed job an agent can be given, its check and its tools (Agents kit)](https://osysharp.com/reference/agent/skills/) — a typed job, its check and its tools
- [Giving an agent work — Do, Ask, Stream, For and Decide (Agents kit)](https://osysharp.com/reference/agent/ask/) — `Do`, `Ask`, `Stream`, `For`, `Decide`
- [What an agent does alone, what it proposes, what it never does — the gate and proposals (Agents kit)](https://osysharp.com/reference/agent/autonomy/) — alone, propose, never; proposals; standing rules
- [An agent asks a person, and waits — the person rung of the ladder of help (Agents kit)](https://osysharp.com/reference/agent/people/) — asking a person, and how work waits
- [Asking for help — an agent that consults a more capable model (Agents kit)](https://osysharp.com/reference/agent/help/) — consulting a more capable model
- [Guards and trying again — the app's own checks on an agent's work, and what happens when work fails (Agents kit)](https://osysharp.com/reference/agent/guards/) — the app's own checks; trying again
- [An agent hands work on to other agents — at once, typed, and never with more than it holds (Agents kit)](https://osysharp.com/reference/agent/delegation/) — handing work to other agents
- [What an agent may spend — a hard limit on every piece of work (Agents kit)](https://osysharp.com/reference/agent/budgets/) — what a piece of work may spend
- [The receipt and the record — what every piece of an agent's work leaves (Agents kit)](https://osysharp.com/reference/agent/task-log/) — the receipt and the record
- [Correcting an agent, and what it is told from then on — corrections, instructions, instruction sets and rollback (Agents kit)](https://osysharp.com/reference/agent/teaching/) — corrections, instructions, instruction sets
- [Who is in charge of an app's agents — every policy in one table, pausing, sponsoring, and trying work again](https://osysharp.com/reference/agent/roles/) — every policy in one table