Agents · in the application

Agents people can trust with real work.

In an Osy# app an agent is a part of the application with a job, an account of its own and a spending limit. It does only what the app says it may, asks a person before anything else, and can never do for somebody what that person may not do themselves. Every piece of its work leaves a record a person can read afterwards.

Build with agents No code · 6 pagesRead the overview

An approval in a person's inbox: the agent proposes to clear a supplier to trade, and says what it looked at first — **An approval in a person's inbox.** The agent that vets suppliers wants to clear a dairy to trade. It may not do that alone, so it asks: this is what will happen, this is what I looked at. A yes runs it as the person who said yes.

01 · What an agent is

A class with a job, an account and a limit.

Four things, and each one is something a person can check.

A job: Typed jobs — “estimate this repair”, “vet this supplier”. What comes back is checked before anybody relies on it.
An account of its own: It signs its work. What it changes is recorded as changed by the agent, for the person it was working for.
Permissions: What it may do alone, what it must propose to a person first, and what it never does. Said nothing, it may only look things up.
A limit: Every piece of work may spend a set amount on the model. When the money runs out the work stops, and keeps what it did.

Beside this is one whole agent. Its tools are the app's own functions, and they run as the agent's account on behalf of whoever asked: a read finds what both may read, a change needs both to be allowed. The Estimator holds Helper, and a helper may not set a price — so the agent cannot either, even for a mechanic who may.

The whole app and its tests

from reference/agent/agents · abridged · its tests run in CIentity Repair {
  [Required, MaxLength(200)] string Fault;
  decimal Price;
  security {
    allow read, update when IsMechanic || IsManager || IsHelper;
    deny update Price when IsHelper;
  }
}

public class EstimateRepair : Skill<Repair, Estimate> {
  public override string Description => "Estimate one repair.";
  public override List<ActionInfo> Tools =>
    [Actions.Of(PartsFor), Actions.Of(NoteRepair), Actions.Of(SetPrice)];
  public override string? Check(Estimate e) =>
    e.Hours <= 0 ? "An estimate takes some time." : null;
}

[Actor(Roles = [ShopRole.Helper])]
public class Estimator : Agent {
  public static Person Principal => new Person { Email = "[email protected]" };
  public override string Purpose => "You estimate bicycle repairs for a small workshop.";
  public override List<SkillBase> Skills => [new EstimateRepair()];
  public override Permits May => Permits.ChangesAlone();
}

// give it work — the answer is an Estimate, checked, or how the work ended
var outcome = await Agents.Of<Estimator>().Do(new EstimateRepair(), repair);

The skill is a typed job — a Repair in, an Estimate out — whose tools are three ordinary functions of the app. The agent class says what it is for, what it holds and what it may do alone. The page this comes from compiles it and runs its tests, with the model scripted, on every change.

02 · What you can build

Start small. Each shape is the one before it, grown.

Start from what the app is for, not from the kits. There are four shapes: an assistant for one person, work done for people with approvals, agents inside a business process, and a team of agents with a coordinator.

A curator asks for a museum label. The agent reads the catalogue and writes it; the curator can correct it.

Shape 1

An assistant for one person

A curator asks for a museum label. The agent reads the catalogue and writes it; the curator can correct it.

The app, whole

After the yes: “It was done, as Tariq Aziz.” The agent did the work; the decision carries a person’s name.

Shape 2

Work done for people, with approvals

After the yes: “It was done, as Tariq Aziz.” The agent did the work; the decision carries a person’s name.

The app, whole

A supplier qualification, drawn by the app. Agents do the reading steps; a person took over the one an agent could not finish.

Shape 3

Agents inside a business process

A supplier qualification, drawn by the app. Agents do the reading steps; a person took over the one an agent could not finish.

The app, whole

One agent in charge, three specialists. One done, one waiting for a person, one stopped when its share of the money ran out.

Shape 4

A team of agents with a coordinator

One agent in charge, three specialists. One done, one waiting for a person, one stopped when its share of the money ran out.

The app, whole

03 · Under people's control

Ten promises.

They hold for every agent in an Osy# app, because they are properties of the language and its runtime, not of a prompt. Each is shown on a real screen.

And one more: an operator can switch the AI off for an app at runtime, and every agent stops taking work. The switch

04 · Six whole stories

Real processes, with the awkward parts left in.

Waits of days, a step that fails, a refusal, a limit that is hit, a person taking over. Each is told as it happened, with the screens the people in it saw.

A supplier is qualified

five days, four agents, one that failed, and a three-day wait

A tool maker qualifies a new supplier of castings. Four agents do the reading steps of a fixed process.

Two suppliers for a bakery group

a week's wait, an outsider's answer, and one agent directing three

A bakery group's purchasing office takes on a flour mill and qualifies a dairy. The mill's own contact fills in a form through a link, with no account.

A parcel that never came

a case owned until it is right, closed, and opened again

A tea shop's customer reports that her order has not arrived. The shop opens an assignment: a piece of work it owns until she has her tea or her money back, with two things that must be true for it to…

A press is repaired

three weeks, a supplier outside, an order refused, and a repair that did not hold

A workshop repairs a customer's press. An agent in charge has three specialists read the fault log, the service history and the manual; the customer fills in a form; a technician is asked to inspect a…

Somebody is hired

four applications, one read by hand, a candidate who withdraws and is erased, and an offer refused

A consultancy fills a role. An agent in charge asks the hiring manager what her request leaves open, has each application read by a second agent, and — weeks later — proposes the offer.

A supplier shuts down

three regions, one stock, a plan refused by the stock, and a plan made again

A pump maker's supplier of housings shuts down. The response is one job with a job under it for each sales region.

05 · Building with agents

The developer's guide starts from the app.

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.

→Know what kind of app you are buildingfour shapes of app with agents in it →Write your first agentan assistant for one person →Know what you must decide, and what holds if you decide nothingwhat you say about an agent, and what holds if you say nothing →See how the kits fit togetherwhich sits on which, and what each one is for →Follow one piece of work through all of itOne piece of work, followed end to end →Choose between two ways of doing somethingI want X, so use Y, not Z, because →Look a word upthe words the Agents guide uses

The kits of the agents family: the core on the left, the kits that stand on their own on the right, and the bridges between them — **Which sits on which, and what each one is for.** The agents family is 29 kits. Two are under everything: `Osysharp.Llm` for every model call and `Osysharp.Agents` for agents themselves.

Write your first agent All 82 reference pages

Every example in the guide is a whole app, compiled and run by the docs gate. Its model is scripted, so it costs nothing and needs no key; in your app that one line names a provider instead — Anthropic, OpenAI or Gemini. What release 1 does not do is listed plainly.