Agents in an Osy# app — what they are, in plain words

An app written in Osy# can have AI agents that people can trust with real work. An agent is a part of the app 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 that a person can read afterwards. This page is the start of the guide; it has no code.

You are here: the start of the Agents guide.

Summary#

A purchasing office is asked to take on a new supplier. Somebody has to look the company up, check its papers, weigh the risk and settle the terms. Most of that is reading and comparing. One step of it is a decision that belongs to a person.

In an app built with Osy#, the reading and comparing can be given to an agent: a part of the app that uses an AI model to do a job. The decision stays with the person. It reaches them like this:

An approval in a person's inbox: the agent proposes to clear a supplier to trade, and says what it looked at first

Tariq leads purchasing at a bakery group. 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, approve or reject.

That picture holds most of what this guide is about. The [[agent-guide-glossary#agent|agent]] did real work. It stopped where its permission ended. A named person decides, seeing exactly what will happen. And if Tariq says yes, the dairy is cleared as Tariq: with his rights, on his name.

Description#

What is an agent, here?#

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

A job. An agent is given typed jobs: "vet this supplier", "write the label for this museum piece". What comes back is checked before anybody relies on it.
An account of its own. The agent signs its work. Everything it changes is recorded as changed by the agent, for the person it was working for.
Permissions. The app says what the agent may do by itself, what it must propose to a person first, and what it may never do. If the app says nothing, the agent may only look things up.
A limit. Every piece of work may spend at most a set amount on the [[agent-guide-glossary#model|AI model]]. When the money runs out the work stops, and keeps what it did.

More on each: What stays under people's control — ten promises, and where each is shown.

What can be built with them?#

Four kinds of thing, from small to large. What you can build — four kinds of app with agents in it shows each one.

An assistant for one person. Somebody asks; the agent does the job; the answer comes back.
Work done for people, with approvals. The agent does what it may and proposes the rest.
Agents inside a [[agent-guide-glossary#process|business process]]. A process with fixed steps runs for days; some steps are an agent's.
A team of agents. One agent is in charge and hands parts of the job to specialists.

What does it look like to the people using it?#

Like the rest of their app. An approval from an agent is one more item in the [[agent-guide-glossary#inbox|inbox]] they already work. A process that agents take part in is drawn and told step by step. One page explains any piece of an agent's work to somebody who was not there. What a person sees — the screens of an app with agents in it goes through the screens.

Is there a whole example?#

Six, each a real process with its awkward parts left in: waits of days, a step that fails, a refusal, a limit that is hit, a person taking over.

A supplier is qualified — five days, four agents, one that failed, and a three-day wait — a tool maker qualifies a new supplier. An agent fails twice, a person steps in, and an approval waits three days.
Two suppliers for a bakery group — a week's wait, an outsider's answer, and one agent directing three — a bakery group takes on a mill and a dairy. A question waits a week for its answer, and one agent directs three others.
A parcel that never came — a case owned until it is right, closed, and opened again — a tea shop's parcel goes missing. The case is settled, closed, and opened again a week later.
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. A supplier outside answers through a link, the manager refuses an order, and the first repair does not hold.
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. One application is read by hand, a candidate withdraws and is erased, and the manager refuses the first 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 shuts down. Three regions draw on one stock, a count finds less than is held, and one region's plan is made again.

What is not in it?#

This is the first release. What release 1 does not include is the plain list of what it does not do.

I am a developer. Where do I go?#

Building with agents — the developer's guide is the developer's guide: what to decide, the smallest working app for each of the four kinds, the map of the kits, and one piece of work followed from start to finish. Every example there is a whole app that is compiled and run.

Go deeper#

Building with agents — the developer's guide — the developer's guide
Glossary — the words the Agents guide uses — every word used here, explained
Agents (a class with a job, its own account, a budget and a record) — the reference pages