Summary#
An agent is a class, and giving it work is a call. The class says what it is for and what it can be asked to do; a skill says what goes in, what comes back and which of your functions it may use.
Writing an agent — a class with a purpose, skills and an account of its own (Agents kit) is one agent whole — its class, its skill, its tools and its tests — compiled and run.
Description#
Its rights are declared, and they are a ceiling. The agent is an account holding the roles its class names. Working for a person, its tools read and change only what both may; a tool its skill does not list never runs (Writing an agent — a class with a purpose, skills and an account of its own (Agents kit), A skill — a typed job an agent can be given, its check and its tools (Agents kit)).
Work is typed, and every way out is a status. Do answers the skill's result type, checked, or says how the
work ended; Ask answers in words; Stream hands an answer on as it arrives (Giving an agent work — Do, Ask, Stream, For and Decide (Agents kit)).
Every piece of work leaves a receipt and a record. Who asked, as whom it ran, what it cost, how it ended — and each step in a plain sentence, chained so a changed line is found (The receipt and the record — what every piece of an agent's work leaves (Agents kit)).
Money is a hard limit. Room is reserved before each call leaves; work whose money runs out is stopped and keeps what it did (What an agent may spend — a hard limit on every piece of work (Agents kit)).
Longer work has an owner. An assignment is a piece of work somebody asked for, owned until its criteria are met; an agent's work is attached to it, and what the agent finds is kept in its repository as items.
People are asked, and what waits for them waits. A question, an approval of one exact version of a thing, a form — put to a person in the inbox they already work, or to somebody with no account through a link — with the answer coming back to the process or the piece of work that waits for it (Requests to people — a question, an approval, a form, and the answer coming back (HumanRequests kit)).
It does alone only what it is trusted with. An agent's class says what it runs by itself, what it must propose to a person first, and what it never does; said nothing, it looks things up alone and proposes the rest. A proposal is the exact call, and a yes runs it as whoever said yes (What an agent does alone, what it proposes, what it never does — the gate and proposals (Agents kit)). In an app with the requests kit it is an approval in that person's inbox (An agent's proposals and questions in a person's inbox, and an inbox item in an agent's hands (Agents.HumanRequests kit)).
It can ask for help. An agent may name a more capable model to consult — by choice, when it is stuck, or when it is not sure of a decision (Asking for help — an agent that consults a more capable model (Agents kit)) — and, when its class says so, a person, whom its work then waits for however long that takes (An agent asks a person, and waits — the person rung of the ladder of help (Agents kit)).
It can hand work on. An agent's class may name skills of other agents — or of its own — that its model hands pieces of its work to, several at once. Each piece has its own receipt under the one that handed it on, is done for the same person, proposes what any piece of work above it would have to propose, and spends out of what is left above it (An agent hands work on to other agents — at once, typed, and never with more than it holds (Agents kit)).
It gets better through people. Somebody who sees its work corrects it; an instruction drawn from the correction reaches the agent only once a person the app trusts with that has made it active; every change to what it is told is a numbered set, a piece of work records the set it ran under, and the agent can be put back to an earlier one (Correcting an agent, and what it is told from then on — corrections, instructions, instruction sets and rollback (Agents kit), and its screens in Correct this, and an agent's Instructions page — the screens people teach an agent on (Agents.Teaching kit)).
Tests cost nothing. A test scripts what the model answers and asserts what the agent then did (Testing an agent without a model — Says, AgentScript and Trajectory (Agents.Testing kit)).
The pages#
Run osy docs agent for the full listing.
How it all fits together — Building with agents — the developer's guide (deciding what to build, four shapes each with a whole app), The map of the kits — which sits on which, and what each one is for (the map of the kits and a page for each), One piece of work, followed end to end (one piece of work through every kit), Choosing — I want X, so use Y, not Z, because (decision tables), Glossary — the words the Agents guide uses
Writing one — Writing an agent — a class with a purpose, skills and an account of its own (Agents kit) (the class, its account, who is in charge), A skill — a typed job an agent can be given, its check and its tools (Agents kit) (typed jobs and tools)
Giving it work — Giving an agent work — Do, Ask, Stream, For and Decide (Agents kit) (
Do,Ask,Stream,For,Decide)What it leaves — The receipt and the record — what every piece of an agent's work leaves (Agents kit) (the receipt, the record and its chain), Privacy for the agent family — agents, the model meter, assignments and work repositories under a person's request (a person's copy, their erasure, and how long it is all kept)
What it costs — What an agent may spend — a hard limit on every piece of work (Agents kit)
What it may do alone — What an agent does alone, what it proposes, what it never does — the gate and proposals (Agents kit) (the gate, proposals, "from now on, alone"), Guards and trying again — the app's own checks on an agent's work, and what happens when work fails (Agents kit) (the app's own checks; trying again)
Teaching it — Correcting an agent, and what it is told from then on — corrections, instructions, instruction sets and rollback (Agents kit) (corrections, instructions a person makes active, instruction sets, rollback), Correct this, and an agent's Instructions page — the screens people teach an agent on (Agents.Teaching kit) ("Correct this" and the Instructions page)
When it is unsure — Asking for help — an agent that consults a more capable model (Agents kit) (a more capable model), An agent asks a person, and waits — the person rung of the ladder of help (Agents kit) (a person; how work waits)
In the inbox — An agent's proposals and questions in a person's inbox, and an inbox item in an agent's hands (Agents.HumanRequests kit) (proposals and questions as requests; handing an item to an agent), What an assignment asks of people — requests as an assignment's work and as inbox items (Assignments.WorkQueues kit) (what an assignment asks of people), What several assignments compete for — shared pools, claims, and what happens when there is less than was thought (Assignments.Allocations kit) (what several assignments compete for)
In a business process — 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 workflow: it waits, fails and is called off with the process, and is charged to the run)
Reading what it did — The inspector — one piece of an agent's work, readable by a person who was not there (Agents.Inspector kit) (one piece of work on one page, for a person who was not there)
Running them — The management screens — where a person runs an app's agents (Agents.Management kit) (the screens: every agent, all the work, who is waited on, standing rules, spending, roles; pause, call off, try again, hand to a person), Who is in charge of an app's agents — every policy in one table, pausing, sponsoring, and trying work again (who may do what, in one table)
Testing it — Testing an agent without a model — Says, AgentScript and Trajectory (Agents.Testing kit)
Calling a model from your own code — The Llm kit — call a model, and know what each call cost (
Llm.Complete, routing, fallback), Typed answers from a model — Llm.Extract<T> and Llm.Decide<T> (Llm kit) (Llm.Extract<T>,Llm.Decide<T>), Model spend — budgets, the meter and the price book (Llm kit) (budgets, the meter, prices), Testing model calls without a model — ScriptedModel (Llm kit) (tests)Turning it off — turning AI off (the runtime switch), the operator's runtime disable
See also#
- Building with agents — the developer's guide — the developer's guide: what to decide, the smallest app for each shape, the map of the kits
- Agents in an Osy# app — what they are, in plain words — the same, for anybody: what agents in an app are, with pictures and no code
- Writing an agent — a class with a purpose, skills and an account of its own (Agents kit) — start here: one agent, whole
- Giving an agent work — Do, Ask, Stream, For and Decide (Agents kit) — giving it work, and what comes back
- The Llm kit — call a model, and know what each call cost — the model calls underneath