diff --git a/.claude/skills/openbot-copy/SKILL.md b/.claude/skills/openbot-copy/SKILL.md index 231b0263f2..1219a78057 100644 --- a/.claude/skills/openbot-copy/SKILL.md +++ b/.claude/skills/openbot-copy/SKILL.md @@ -23,6 +23,7 @@ One word for one thing, everywhere a person can see it. |---|---|---| | **Bot**, **Bots** (capitalised) | What a person creates, talks to and gives work to. | agent, coworker, assistant, AI | | **agent** | Only an outside framework's program, in the places that are about connecting one: "an agent you already run", "AG-UI agent". | Bot, when the thing is a Bot | +| **agent**, **Agents** | What a Bot hands work to, listed on the Agents page: OpenBot's own, a framework OpenBot runs, or one you run. Never for the Bot itself. | Bot, worker, subagent | | **app** | A service a Bot uses: Gmail, Google Drive, Notion. | connector, integration, plugin | | **Connections** | The page that lists the apps and accounts every Bot uses as you: the every-Bot page of Apps. On a Bot's page the same thing is the **Apps** row. | connected accounts, linked accounts | | **connect / disconnect / reconnect** | What a person does to their own account. | link (except GitHub and Slack identity, where "link" is the vendor's own word) | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d36f230750..da856ba559 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -195,7 +195,8 @@ jobs: # one color in the sidebar, on its page and at the top of its conversation, Record on # screen with a Bot's page in a window of any width, the team screens and a Bot's # Publish dialog holding their layout wide, narrow and on a phone, and the Admin screens - # where a rule or a grant names a team holding theirs wide and on a phone, which only a + # where a rule or a grant names a team holding theirs wide and on a phone, a Needs you row read + # whole at a phone's width and a chat's with its answers on a line of their own, which only a # browser's layout, cascade # and paint resolve, and the app following the system's light or dark, which only a # browser's `prefers-color-scheme` reports, with what OpenBot Desktop's window is told of @@ -204,7 +205,7 @@ jobs: # test script's pretest does). - run: | bun run generate:app-config - bun test app/tests/tool-line-reduced-motion.test.tsx app/tests/onboarding-window-buttons.test.tsx app/tests/onboarding-orb-room.test.tsx app/tests/transcript-rail-clearance.test.tsx app/tests/a2ui-frame.test.tsx app/tests/update-banner-layout.test.tsx app/tests/composer-dictation-notice-layout.test.tsx app/tests/conversation-intro-halo.test.tsx app/tests/transcript-room.test.tsx app/tests/skins-window-buttons.test.tsx app/tests/opendots-rail-badge.test.tsx app/tests/account-version-layout.test.tsx app/tests/organization-menu-names.test.tsx app/tests/bot-orb-one-color.test.tsx app/tests/theme-follows-system.test.tsx app/tests/desktop-window-theme.test.tsx app/tests/bot-screen-record-layout.test.tsx app/tests/teams-screens-layout.test.tsx app/tests/team-grants-screens-layout.test.tsx + bun test app/tests/tool-line-reduced-motion.test.tsx app/tests/onboarding-window-buttons.test.tsx app/tests/onboarding-orb-room.test.tsx app/tests/transcript-rail-clearance.test.tsx app/tests/a2ui-frame.test.tsx app/tests/update-banner-layout.test.tsx app/tests/composer-dictation-notice-layout.test.tsx app/tests/conversation-intro-halo.test.tsx app/tests/transcript-room.test.tsx app/tests/skins-window-buttons.test.tsx app/tests/opendots-rail-badge.test.tsx app/tests/account-version-layout.test.tsx app/tests/organization-menu-names.test.tsx app/tests/bot-orb-one-color.test.tsx app/tests/theme-follows-system.test.tsx app/tests/desktop-window-theme.test.tsx app/tests/bot-screen-record-layout.test.tsx app/tests/teams-screens-layout.test.tsx app/tests/team-grants-screens-layout.test.tsx app/tests/needs-you-board-layout.test.tsx env: OPENBOT_APP_BROWSER: '1' # The desktop setup window's, for the same reason: the AI step's form holding still while the diff --git a/api/README.md b/api/README.md index 2d6ec188f2..26d16a0e05 100644 --- a/api/README.md +++ b/api/README.md @@ -32,6 +32,7 @@ not touch the same lines: | `passwords-and-recorder.yaml` | Sign-in requests, saved logins and the Recorder | | `learning.yaml` | OpenBot's side of Automatic learning: Learning settings, each person's spaces and sharing choices, sharing requests, and the skills delivered to Bots | | `memory.yaml` | A person's memories and memory sources | +| `agents.yaml` | The agents Bots hand work to (`bot-agents`), their callback tokens, and each Bot's delegation | An area file holds its operations under `paths`, and under `components` the schemas, parameters, responses and examples only it uses. Inside the file, refer to them as usual diff --git a/api/openapi-harnesses.test.ts b/api/openapi-harnesses.test.ts index 9b39d6aafc..b3290a5c77 100644 --- a/api/openapi-harnesses.test.ts +++ b/api/openapi-harnesses.test.ts @@ -9,24 +9,30 @@ import { declaredHarness, HARNESSES } from "../shared/harnesses"; * checks every create against the harness catalogue. The two are one list: a framework added to the * catalogue without the spec is refused by every generated client before it is sent, and one left in * the spec after the catalogue drops it is refused by the server. Empty is how a create says it named - * none. + * none. A Bot made with its own address names one (CreateBotRequest), and so does an agent added to + * the organization's list (BotAgentHarness). */ -test("the spec's harness enum is exactly the frameworks the server accepts", () => { - const spec = parse( - readFileSync(join(import.meta.dir, "openapi.yaml"), "utf8"), - ) as { - components: { - schemas: Record< - string, - { properties?: Record } - >; - }; +const spec = parse( + readFileSync(join(import.meta.dir, "openapi.yaml"), "utf8"), +) as { + components: { + schemas: Record< + string, + { enum?: string[]; properties?: Record } + >; }; - const harness = spec.components.schemas.CreateBotRequest?.properties?.harness; - const accepted = HARNESSES.filter((entry) => declaredHarness(entry.id)).map( - (entry) => entry.id, - ); +}; +const accepted = HARNESSES.filter((entry) => declaredHarness(entry.id)).map( + (entry) => entry.id, +); +test("the spec's harness enum is exactly the frameworks the server accepts", () => { + const harness = spec.components.schemas.CreateBotRequest?.properties?.harness; expect(accepted.length).toBeGreaterThan(0); expect([...(harness?.enum ?? [])].sort()).toEqual(["", ...accepted].sort()); }); + +test("an agent's harness enum is the same list", () => { + const harness = spec.components.schemas.BotAgentHarness; + expect([...(harness?.enum ?? [])].sort()).toEqual(["", ...accepted].sort()); +}); diff --git a/api/openapi.yaml b/api/openapi.yaml index 6b3ed60cbb..e713c6daf2 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -115,6 +115,8 @@ tags: description: 'Automatic learning: the skills Learning proposed, the evidence behind them, approving and rejecting them, and its runs, in the organization''s spaces and each person''s own; which space each Bot learns into, who reviews what people''s recordings propose, each person''s sharing choices, requests to share a skill with every Bot, and the skills delivered to Bots.' - name: Memory description: 'The facts a person''s Bots remember about them, and the app actions those facts are read in from. Each person''s are theirs alone: an administrator can''t read them either.' + - name: Agents + description: 'The agents an organization''s Bots hand work to: OpenBot''s own, a framework OpenBot runs, or an agent somebody runs at its own address. An administrator adds the organization''s, and anybody may add a private one for their own Bots. A Bot''s delegation says whether it works on one agent or hands work to several, and which.' paths: /api/v2/organizations/{organizationId}/reactions: parameters: @@ -3753,6 +3755,51 @@ paths: $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/tasks/{taskId}/turns: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TaskId' + get: + tags: + - Tasks + operationId: listTaskTurns + summary: List a task's turns + description: 'Return one page of the turns a task has finished, oldest first: each time its Bot worked on something it was asked in the task''s conversation, the Bot''s brief or a line the person said there. Each says how long the Bot worked on it, counting only the time its runs took, never the time it waited on the person, and which model answered. A turn still running is not listed until it ends. Another person''s task is not found. A missing cursor starts at the first page and nextCursor null ends the list.' + security: + - webSession: [] + - appOAuth: + - tasks:read + - apiKey: [] + parameters: + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Cursor' + responses: + '200': + description: One page of the task's turns. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskTurnPage' + examples: + example: + $ref: '#/components/examples/TaskTurnPageExample' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TaskNotFound' + '500': + $ref: '#/components/responses/ServerError' + '503': + $ref: '#/components/responses/ServiceUnavailable' + default: + $ref: '#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/tasks/{taskId}/resolve: parameters: - $ref: '#/components/parameters/OrganizationId' @@ -3891,6 +3938,52 @@ paths: $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/tasks/{taskId}/stop: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TaskId' + post: + tags: + - Tasks + operationId: stopTask + summary: Stop a task + description: Stop the task's work, as Stop in its conversation does. A step it is in the middle of is cut off; the steps it finished stay done, and its conversation and the one that asked for it say how far it got. What it waits on the person for is no longer asked. Only a task that is working or waiting on the person can be stopped. The answer is the task as it stands now, which is stopped. + security: + - webSession: [] + - appOAuth: + - tasks:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '200': + description: The task as it stands now. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + example: + $ref: '#/components/examples/TaskResponseExample' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TaskNotFound' + '409': + $ref: '#/components/responses/TaskConflict' + '500': + $ref: '#/components/responses/ServerError' + '503': + $ref: '#/components/responses/ServiceUnavailable' + default: + $ref: '#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/transcriptions: parameters: - $ref: '#/components/parameters/OrganizationId' @@ -19401,6 +19494,443 @@ paths: $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents: + parameters: + - $ref: '#/components/parameters/OrganizationId' + get: + tags: + - Agents + operationId: listBotAgents + summary: List agents + description: 'Return one page of the agents the caller can see: the organization''s public agents and the caller''s own private ones, oldest first, and by id among agents made at the same moment. Somebody else''s private agent is never among them. scope=organization lists every agent in the organization, people''s private ones included, for an admin''s screens; it is refused to anybody who is not an admin of the organization. A missing cursor starts at the first page and nextCursor null ends the list.' + security: + - webSession: [] + - appOAuth: + - bot-agents:read + - apiKey: [] + parameters: + - name: scope + in: query + description: 'Whose agents: caller, the agents the caller can see; organization, every agent in the organization, for an admin of it only.' + schema: + type: string + enum: + - caller + - organization + default: caller + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Cursor' + responses: + '200': + description: One page of agents. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentPage' + examples: + lastPage: + $ref: '#/components/examples/BotAgentPageLast' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + post: + tags: + - Agents + operationId: createBotAgent + summary: Add an agent + description: Add an agent for Bots to hand work to. kind openbot runs inside OpenBot, on the model given or the organization's default. kind address runs at an AG-UI address, which the server checks before saving; a key, when given, is stored encrypted and never returned. Anybody may add a private agent, for their own Bots; only an admin of the organization may add a public one, which every member's Bots may use. A repeated request with the same Idempotency-Key and body returns the first result. + security: + - webSession: [] + - appOAuth: + - bot-agents:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBotAgentRequest' + examples: + openbot: + summary: OpenBot's own agent, on a model of its own. + value: + name: Researcher + description: Deep research on the web and in the person's apps, with sources. + visibility: public + kind: openbot + model: null + address: + summary: An agent somebody runs themselves, behind a key. + value: + name: Pipeline analyst + description: Reads the sales pipeline and forecasts the quarter. + visibility: private + kind: address + endpoint: https://agents.example.com/ag-ui + auth: + header: Authorization + value: Bearer example-key + harness: langgraph + skills: + - name: Forecast + description: Forecasts the quarter from the open deals. + examples: + - What will we close this quarter? + responses: + '201': + description: The agent was added. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + Location: + description: The new agent's address. + schema: + type: string + example: /api/v2/organizations/default/bot-agents/bag_4f7c1e2a9d0b4c63 + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + created: + $ref: '#/components/examples/CreatedBotAgent' + '400': + $ref: '#/components/responses/InvalidBotAgent' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotAgentId' + get: + tags: + - Agents + operationId: getBotAgent + summary: Read one agent + description: Return one agent the caller can see. An agent that does not exist, was deleted, or is private to somebody else is not found. + security: + - webSession: [] + - appOAuth: + - bot-agents:read + - apiKey: [] + responses: + '200': + description: The agent. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + openbot: + $ref: '#/components/examples/OpenBotAgent' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + patch: + tags: + - Agents + operationId: updateBotAgent + summary: Change an agent + description: 'Replace an agent''s name, description and visibility, which are all required, and change any optional field that is present. An absent endpoint, key, model or skills leaves that setting as it is, so an edit to a name never drops a key. Only whoever may manage the agent may change it: its owner for a private one, an admin for a public one. Only an admin may make an agent public. kind cannot change. Every Bot that uses the agent runs on the change from its next turn.' + security: + - webSession: [] + - appOAuth: + - bot-agents:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateBotAgentRequest' + examples: + rename: + value: + name: Research desk + description: Deep research on the web and in the person's apps, with sources. + visibility: public + responses: + '200': + description: The changed agent. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + renamed: + $ref: '#/components/examples/CreatedBotAgent' + '400': + $ref: '#/components/responses/InvalidBotAgent' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + delete: + tags: + - Agents + operationId: deleteBotAgent + summary: Delete an agent + description: 'Delete an agent and retire its key and callback token. It is taken off every Bot that may use it. Refused, with BOT_AGENT_IN_USE, while it is the only agent of any Bot, deleted Bots aside: give that Bot another agent first. The refusal names those Bots the caller can see and only counts the rest. Only whoever may manage the agent may delete it. Task threads it worked in stay readable. An agent that is already deleted is not found.' + security: + - webSession: [] + - appOAuth: + - bot-agents:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '204': + description: The agent was deleted. + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: '#/components/responses/BotAgentInUse' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}/issue-callback-token: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotAgentId' + post: + tags: + - Agents + operationId: issueBotAgentCallbackToken + summary: Issue an agent's callback token + description: 'Give an agent at an address a new credential for calling OpenBot''s tools back, and return it this once: it is never returned again, and the audit trail records that one was issued, never what it is. Issuing one for an agent that has one replaces it, which is how a leaked token is retired. A call made with it is allowed only for a run of a Bot that may use this agent, as the person that run is for. Only whoever may manage the agent may issue one. An agent that runs inside OpenBot, or at an address OpenBot runs itself, needs none and is refused.' + security: + - webSession: [] + - appOAuth: + - bot-agents:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '200': + description: The new token, shown once. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentCallbackToken' + examples: + issued: + $ref: '#/components/examples/BotAgentCallbackTokenExample' + '400': + $ref: '#/components/responses/InvalidBotAgent' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}/revoke-callback-token: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotAgentId' + post: + tags: + - Agents + operationId: revokeBotAgentCallbackToken + summary: Revoke an agent's callback token + description: Take away an agent's credential for calling OpenBot's tools back. It still answers in a conversation; it can't reach anything outside one. Only whoever may manage the agent may revoke it. Revoking a token that is not there changes nothing. + security: + - webSession: [] + - appOAuth: + - bot-agents:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '200': + description: The agent, with no callback token. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + revoked: + $ref: '#/components/examples/CreatedBotAgent' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bots/{botId}/delegation: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotId' + get: + tags: + - Agents + operationId: getBotDelegation + x-openbot-singleton: true + summary: Read a Bot's delegation + description: 'Return how a Bot the caller can see works: on its own agent (mode self, every Bot made before agents were a list), or handing work to the agents it may use (mode orchestrate). The first agent is its default: a Bot in mode self runs on it, and a Bot in mode orchestrate hands it work the Bot names no agent for and every run nobody is waiting on (a routine, a check-in, a goal, another Bot''s hand-off, a group conversation). Whoever uses a Bot uses its agents: an agent that is private to the Bot''s owner still does the work for everybody the Bot is shared with, and to anybody else it is named Private agent, with its description withheld. An agent that was deleted, or that the Bot''s owner can no longer use, is listed with available false, and the Bot hands it nothing.' + security: + - webSession: [] + - appOAuth: + - bots:read + - apiKey: [] + responses: + '200': + description: The Bot's delegation. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotDelegation' + examples: + self: + $ref: '#/components/examples/SelfBotDelegation' + orchestrate: + $ref: '#/components/examples/OrchestratingBotDelegation' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/BotNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + put: + tags: + - Agents + operationId: replaceBotDelegation + summary: Set a Bot's delegation + description: 'Replace how a Bot works. Mode self takes exactly one agent, which the Bot runs on with its apps, as every Bot did before agents were a list. Mode orchestrate takes one to twenty agents, in order, the first being the default: the Bot then answers on its own model with only the tools for replying, reacting, finding a task''s thread and handing work to an agent, plus reading the person''s memory, and each agent works with the Bot''s apps as the person who asked. model and effort are the Bot''s own when it orchestrates, one the model catalogue offers, or null for the organization''s default; they are ignored in mode self. instructions steer how it hands work out and answers, and are read only in mode orchestrate. Every agent named must be one the caller can see, or one the Bot already has. Only whoever may manage the Bot may change it, and a Bot that comes with OpenBot cannot be changed.' + security: + - webSession: [] + - appOAuth: + - bots:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReplaceBotDelegationRequest' + examples: + orchestrate: + value: + mode: orchestrate + model: null + effort: null + instructions: Hand research to Researcher and anything about the pipeline to Pipeline analyst. Answer greetings yourself. + agentIds: + - bag_4f7c1e2a9d0b4c63 + - bag_9a2d7e1c3b5f4086 + responses: + '200': + description: The Bot's delegation after the change. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotDelegation' + examples: + orchestrate: + $ref: '#/components/examples/OrchestratingBotDelegation' + '400': + $ref: '#/components/responses/InvalidBotDelegation' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotForbidden' + '404': + $ref: '#/components/responses/BotNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' components: securitySchemes: webSession: @@ -19511,6 +20041,8 @@ components: learning:write: Approve and reject what Learning proposed and start Learning in the signed-in person's own spaces, change their Learning choices, and for an administrator change the organization's Learning settings and decide sharing requests. memories:read: Read the signed-in person's memories and memory sources. memories:write: Write, change and forget the signed-in person's memories, and add, change, sync and remove their memory sources. + bot-agents:read: Read the agents the signed-in person's Bots may hand work to, and for an administrator every agent in the organization. + bot-agents:write: Add, change and delete the signed-in person's own agents and their callback tokens, and for an administrator the organization's. apiKey: type: http scheme: bearer @@ -20234,6 +20766,17 @@ components: maxLength: 200 pattern: \S example: 0f3a9c2e-7b1d-4e8a-a6c5-2d9e4f1b8c70 + BotAgentId: + name: botAgentId + in: path + required: true + description: The agent's id. + schema: + type: string + minLength: 1 + maxLength: 200 + pattern: \S + example: bag_4f7c1e2a9d0b4c63 headers: PrivateNoStore: description: A Bot is private to the caller. @@ -23889,6 +24432,22 @@ components: botId: type: string description: The Bot doing it. + agent: + type: + - object + - 'null' + description: The agent doing the work, when the Bot handed it to one of the agents it may use. Null for a task the Bot does itself, which is every task before agents were a list. Absent from a server that does not name it. + additionalProperties: false + required: + - id + - name + properties: + id: + type: string + description: The agent's id. + name: + type: string + description: What the agent is called. An agent private to somebody other than the caller is named Private agent. conversationId: type: string description: The task's own conversation, where the person reads it and replies. @@ -24017,6 +24576,58 @@ components: properties: task: $ref: '#/components/schemas/Task' + TaskTurn: + type: object + description: One finished turn of a task's work, answering one thing it was asked in its conversation. + required: + - askId + - startedAt + - endedAt + - workedSeconds + - runs + - model + properties: + askId: + type: string + description: The id of the message the turn answered, as the conversation's history names it. + startedAt: + type: string + format: date-time + description: When its first run began. + endedAt: + type: string + format: date-time + description: When its last run ended. + workedSeconds: + type: integer + minimum: 0 + description: How long its runs took, added up. A wait on the person between two runs (an approval, a question) is not counted. + runs: + type: integer + minimum: 1 + description: How many runs it took. More than one when it stopped for the person and carried on after. + model: + type: + - string + - 'null' + description: The model its last run used. Null when the Bot chooses its own model and did not name it. + TaskTurnPage: + type: object + required: + - turns + - nextCursor + properties: + turns: + type: array + items: + $ref: '#/components/schemas/TaskTurn' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. TranscriptionUpload: type: object required: @@ -35038,6 +35649,390 @@ components: maxLength: 4096 pattern: ^[A-Za-z0-9_-]+$ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + BotAgentKind: + type: string + enum: + - openbot + - address + description: 'openbot: runs inside OpenBot. address: runs at an AG-UI address, somebody''s own or a framework OpenBot runs itself.' + BotAgentVisibility: + type: string + enum: + - public + - private + description: 'public: every member''s Bots may use it, and only an admin may make one. private: only its owner''s Bots may use it.' + BotAgentSkill: + type: object + description: One thing the agent is good at, in the shape of an A2A Agent Card's skill. A Bot reads its agents' skills when it decides which to hand work to. + additionalProperties: false + required: + - name + - description + properties: + name: + type: string + minLength: 1 + maxLength: 80 + pattern: \S + description: The skill's name, 1 to 80 characters once trimmed. + description: + type: string + minLength: 1 + maxLength: 500 + pattern: \S + description: What it does, 1 to 500 characters once trimmed. + examples: + type: array + maxItems: 5 + description: Up to five things a person might ask for that it handles. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: \S + BotAgent: + type: object + description: 'An agent as the caller sees it. canManage, mine and builtIn are the server''s verdicts for this caller; a client renders them and never recomputes them. No secret is ever part of an agent: hasAuth and hasCallbackToken say whether one is set.' + required: + - id + - name + - description + - kind + - visibility + - endpoint + - model + - skills + - hasAuth + - hasCallbackToken + - builtIn + - canManage + - mine + - botCount + - createdAt + - updatedAt + properties: + id: + type: string + description: The agent's id. + name: + type: string + description: What the agent is called. + description: + type: string + description: What it is good at, in its owner's words. A Bot reads it when it decides which agent to hand work to. + kind: + $ref: '#/components/schemas/BotAgentKind' + visibility: + $ref: '#/components/schemas/BotAgentVisibility' + endpoint: + type: + - string + - 'null' + description: The AG-UI address it runs at, as it was stored. Null for an agent that runs inside OpenBot. + framework: + type: string + description: What runs it, by the name a person reads ("LangChain", "OpenBot"). Absent when OpenBot doesn't know. + model: + type: + - string + - 'null' + description: The model it runs on, for an agent whose model is OpenBot's to choose. Null for the organization's default, or for an agent that picks its own. + skills: + type: array + items: + $ref: '#/components/schemas/BotAgentSkill' + hasAuth: + type: boolean + description: Whether a key is set for its address. Never the key. + hasCallbackToken: + type: boolean + description: Whether it holds a credential for calling OpenBot's tools back. Never the credential. + builtIn: + type: boolean + description: Whether OpenBot runs it, inside OpenBot or at an address OpenBot started, so it needs no callback token of its own. + canManage: + type: boolean + description: Whether the caller may change and delete it. + mine: + type: boolean + description: Whether the caller added it. + botCount: + type: integer + minimum: 0 + description: 'How many of the Bots the caller can see may use it, deleted Bots aside. A count only: which Bots is not said. With scope=organization, every Bot in the organization.' + createdAt: + type: string + format: date-time + description: When it was added. + updatedAt: + type: string + format: date-time + description: When it last changed. + BotAgentPage: + type: object + required: + - agents + - nextCursor + properties: + agents: + type: array + items: + $ref: '#/components/schemas/BotAgent' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + BotAgentName: + type: string + minLength: 1 + maxLength: 80 + pattern: \S + description: What the agent is called, 1 to 80 characters once trimmed. + BotAgentDescription: + type: string + minLength: 1 + maxLength: 1000 + pattern: \S + description: What it is good at, 1 to 1000 characters once trimmed. A Bot reads it when it decides which agent to hand work to, so say what to send it. + BotAgentEndpoint: + type: string + description: 'The AG-UI address it runs at: an absolute http or https address. An address that fits can still be refused: the server refuses one this organization may not reach, and one that does not answer a real AG-UI run.' + maxLength: 2048 + format: uri + pattern: ^[Hh][Tt][Tt][Pp][Ss]?:// + BotAgentKey: + type: object + description: 'A key the agent''s address sits behind. Write-only: stored encrypted and never returned. A blank value sets no key.' + additionalProperties: false + required: + - value + properties: + header: + type: string + maxLength: 200 + pattern: ^[A-Za-z0-9-]*$ + description: The header it is sent in. Blank or absent means Authorization. + value: + type: string + maxLength: 8000 + writeOnly: true + description: The header's value. + BotAgentHarness: + type: string + description: The framework an agent at an address is built on, by its id in OpenBot's harness list (shared/harnesses.json). Empty means none was named. Kept only for kind address. + enum: + - '' + - crewai + - llamaindex + - agno + - langgraph + - google-adk + - antigravity + - pydantic-ai + - microsoft-agent-framework + - claude-agent-sdk + - strands + - ag2 + - langroid + - mastra + BotAgentModel: + type: + - string + - 'null' + minLength: 1 + maxLength: 500 + pattern: \S + description: A model the catalogue offers, or null for the organization's default. Read only for an agent whose model is OpenBot's to choose. + BotAgentSkills: + type: array + maxItems: 20 + description: Up to twenty things it is good at. Absent on a change leaves them as they are. + items: + $ref: '#/components/schemas/BotAgentSkill' + CreateBotAgentRequest: + type: object + description: A new agent. endpoint is required for kind address and refused for kind openbot. + additionalProperties: false + required: + - name + - description + - visibility + - kind + properties: + name: + $ref: '#/components/schemas/BotAgentName' + description: + $ref: '#/components/schemas/BotAgentDescription' + visibility: + $ref: '#/components/schemas/BotAgentVisibility' + kind: + $ref: '#/components/schemas/BotAgentKind' + endpoint: + $ref: '#/components/schemas/BotAgentEndpoint' + auth: + $ref: '#/components/schemas/BotAgentKey' + harness: + $ref: '#/components/schemas/BotAgentHarness' + model: + $ref: '#/components/schemas/BotAgentModel' + skills: + $ref: '#/components/schemas/BotAgentSkills' + BotAgentResponse: + type: object + required: + - agent + properties: + agent: + $ref: '#/components/schemas/BotAgent' + UpdateBotAgentRequest: + type: object + description: An agent's fields after the change. Absent optional fields stay as they are. + additionalProperties: false + required: + - name + - description + - visibility + properties: + name: + $ref: '#/components/schemas/BotAgentName' + description: + $ref: '#/components/schemas/BotAgentDescription' + visibility: + $ref: '#/components/schemas/BotAgentVisibility' + endpoint: + $ref: '#/components/schemas/BotAgentEndpoint' + auth: + $ref: '#/components/schemas/BotAgentKey' + model: + $ref: '#/components/schemas/BotAgentModel' + skills: + $ref: '#/components/schemas/BotAgentSkills' + BotAgentCallbackToken: + type: object + required: + - token + properties: + token: + type: string + minLength: 1 + description: The agent's credential for calling OpenBot's tools back. Returned this once and never again. + BotDelegationMode: + type: string + enum: + - self + - orchestrate + description: 'self: the Bot runs on its one agent with its apps. orchestrate: the Bot answers on its own model and hands work to the agents it may use.' + BotDelegationAgent: + type: object + description: One agent a Bot may use, as the caller sees it. + required: + - id + - name + - description + - kind + - available + properties: + id: + type: string + description: The agent's id. + name: + type: string + description: What the agent is called. An agent private to somebody other than the caller is named Private agent. + description: + type: string + description: What it is good at. Empty for an agent private to somebody other than the caller. + kind: + $ref: '#/components/schemas/BotAgentKind' + framework: + type: string + description: What runs it, by the name a person reads. Absent when OpenBot doesn't know. + available: + type: boolean + description: 'Whether the Bot may still hand it work: false once the agent is deleted, or private to somebody other than the Bot''s owner.' + BotDelegation: + type: object + description: How a Bot works, and the agents it may use, the first being its default. + required: + - botId + - mode + - model + - effort + - instructions + - agents + - canManage + properties: + botId: + type: string + description: The Bot's id. + mode: + $ref: '#/components/schemas/BotDelegationMode' + model: + type: + - string + - 'null' + description: The model the Bot answers on when it orchestrates, or null for the organization's default. + effort: + type: + - string + - 'null' + description: How hard it thinks when it orchestrates, or null for the model's own. + instructions: + type: string + description: How it hands work out and answers when it orchestrates. May be empty. Empty for a caller who can't change the Bot, since it can name an agent private to its owner. + agents: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/BotDelegationAgent' + canManage: + type: boolean + description: Whether the caller may change it. + ReplaceBotDelegationRequest: + type: object + additionalProperties: false + required: + - mode + - model + - effort + - instructions + - agentIds + properties: + mode: + $ref: '#/components/schemas/BotDelegationMode' + model: + type: + - string + - 'null' + minLength: 1 + maxLength: 500 + pattern: \S + description: A model the catalogue offers, or null for the default. Trimmed. + effort: + type: + - string + - 'null' + minLength: 1 + maxLength: 40 + pattern: \S + description: An effort the model takes, or null for its own. Trimmed, and read in lower case. + instructions: + type: string + maxLength: 4000 + description: How it hands work out and answers, up to 4000 characters. May be empty. + agentIds: + type: array + minItems: 1 + maxItems: 20 + uniqueItems: true + description: The agents it may use, in order, the first being its default. Exactly one in mode self. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: \S responses: InvalidRequest: description: A parameter is malformed. @@ -40048,6 +41043,129 @@ components: retryable: false requestId: req_example traceId: trace_example + InvalidBotAgent: + description: A field is missing or out of bounds, kind and endpoint don't agree, the address is one this organization may not reach or did not answer a real AG-UI run, the model is not one the catalogue offers, or the agent runs inside OpenBot and so takes no callback token. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + description: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: Say what this agent is good at, so your Bots know what to send it. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + unreachable: + value: + type: https://open.bot/errors/bot-agent-unreachable + title: Couldn't reach that agent. + status: 400 + detail: Couldn't reach an agent at that address. Check the address and its key, then try again. + code: BOT_AGENT_UNREACHABLE + category: validation + retryable: false + requestId: req_example + traceId: trace_example + BotAgentForbidden: + description: The caller may not manage this agent, or only an admin may make an agent public. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + notYours: + value: + type: https://open.bot/errors/permission-denied + title: You can't manage this agent. + status: 403 + detail: You can't manage this agent. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + publicAdminOnly: + value: + type: https://open.bot/errors/permission-denied + title: Only an admin can share an agent with everyone. + status: 403 + detail: Only an admin can share an agent with everyone. Keep it private to use it with your own Bots. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + BotAgentNotFound: + description: The agent does not exist, was deleted, or is not visible to the caller, or the organization is not. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + missing: + value: + type: https://open.bot/errors/bot-agent-not-found + title: Agent not found. + status: 404 + detail: Couldn't find that agent. + code: BOT_AGENT_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + BotAgentInUse: + description: The agent is the only agent of a Bot, or a repeated request with the same Idempotency-Key had a different body. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + onlyAgent: + value: + type: https://open.bot/errors/bot-agent-in-use + title: A Bot runs on this agent alone. + status: 409 + detail: Quote Checker and 1 other Bot run on this agent alone. Give them another agent first, then delete this one. + code: BOT_AGENT_IN_USE + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + InvalidBotDelegation: + description: A field is missing or out of bounds, mode self names other than one agent, an agent named is not one the caller can see, or the model or effort is not one the catalogue offers. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + selfTakesOne: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A Bot that works on its own runs on one agent. Turn on handing work to agents to choose more. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + unknownAgent: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: Couldn't find one of those agents. Choose from the agents you can see. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example examples: ReactionPageLast: summary: Every reaction in a conversation, on one page. @@ -41013,6 +42131,17 @@ components: resolvedAt: null createdAt: '2026-11-14T09:00:00.000Z' updatedAt: '2026-11-14T09:05:00.000Z' + TaskTurnPageExample: + summary: 'One turn: the Bot''s brief, worked on for 52 seconds.' + value: + turns: + - askId: 3a1c9e2b-5d40-4f7a-8b61-0e9d2c4f7a13 + startedAt: '2026-11-14T09:00:02.000Z' + endedAt: '2026-11-14T09:00:54.000Z' + workedSeconds: 52 + runs: 1 + model: gpt-5.1 + nextCursor: null TranscriptionExample: summary: What was said. value: @@ -43928,3 +45057,113 @@ components: query: type: string nextCursor: null + BotAgentPageLast: + summary: The last page. + value: + agents: + - id: bag_0c51d9e3a7f24b18 + name: OpenBot + description: OpenBot's own agent, with every app and component the Bot may use. + kind: openbot + visibility: public + endpoint: null + framework: OpenBot + model: null + skills: [] + hasAuth: false + hasCallbackToken: false + builtIn: true + canManage: false + mine: false + botCount: 4 + createdAt: '2026-11-16T09:00:00Z' + updatedAt: '2026-11-16T09:00:00Z' + nextCursor: null + CreatedBotAgent: + summary: An agent a person added at their own address. + value: + agent: + id: bag_4f7c1e2a9d0b4c63 + name: Pipeline analyst + description: Reads the sales pipeline and forecasts the quarter. + kind: address + visibility: private + endpoint: https://agents.example.com/ag-ui + framework: LangChain + model: null + skills: + - name: Forecast + description: Forecasts the quarter from the open deals. + examples: + - What will we close this quarter? + hasAuth: true + hasCallbackToken: false + builtIn: false + canManage: true + mine: true + botCount: 0 + createdAt: '2026-11-16T09:30:00Z' + updatedAt: '2026-11-16T09:30:00Z' + OpenBotAgent: + summary: OpenBot's own agent. + value: + agent: + id: bag_0c51d9e3a7f24b18 + name: OpenBot + description: OpenBot's own agent, with every app and component the Bot may use. + kind: openbot + visibility: public + endpoint: null + framework: OpenBot + model: null + skills: [] + hasAuth: false + hasCallbackToken: false + builtIn: true + canManage: false + mine: false + botCount: 4 + createdAt: '2026-11-16T09:00:00Z' + updatedAt: '2026-11-16T09:00:00Z' + BotAgentCallbackTokenExample: + summary: A new token. + value: + token: obot_agt_7f3a9c2e5d1b4f60a8e2c9d4b1f7e3a6c0d9 + SelfBotDelegation: + summary: A Bot that runs on its own agent, as every Bot did before agents were a list. + value: + botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21 + mode: self + model: null + effort: null + instructions: '' + agents: + - id: bag_0c51d9e3a7f24b18 + name: OpenBot + description: OpenBot's own agent, with every app and component the Bot may use. + kind: openbot + framework: OpenBot + available: true + canManage: true + OrchestratingBotDelegation: + summary: A Bot that hands work to two agents. + value: + botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21 + mode: orchestrate + model: null + effort: null + instructions: Hand research to Researcher and anything about the pipeline to Pipeline analyst. Answer greetings yourself. + agents: + - id: bag_4f7c1e2a9d0b4c63 + name: Researcher + description: Deep research on the web and in the person's apps, with sources. + kind: openbot + framework: OpenBot + available: true + - id: bag_9a2d7e1c3b5f4086 + name: Pipeline analyst + description: Reads the sales pipeline and forecasts the quarter. + kind: address + framework: LangChain + available: true + canManage: true diff --git a/api/openapi/agents.yaml b/api/openapi/agents.yaml new file mode 100644 index 0000000000..a283227867 --- /dev/null +++ b/api/openapi/agents.yaml @@ -0,0 +1,1146 @@ +# Agents: the agents an organization's Bots hand work to, and each Bot's delegation. +# +# One area of OpenBot's REST API. `bun run api:bundle` joins every area with common.yaml into +# api/openapi.yaml, the file every client and check reads. See api/README.md. +# +# The path noun is `bot-agents`, not `agents`: Intelligence's API already uses `agentId` for the +# runtime agent a thread ran on (in OpenBot, a Bot), and names under an organization that are not a +# Bot's could one day be Intelligence's. Intelligence has no Bots, so a `bot-` name cannot collide. +paths: + /api/v2/organizations/{organizationId}/bot-agents: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + get: + tags: [Agents] + operationId: listBotAgents + summary: List agents + description: >- + Return one page of the agents the caller can see: the organization's + public agents and the caller's own private ones, oldest first, and by + id among agents made at the same moment. Somebody else's private agent + is never among them. scope=organization lists every agent in the + organization, people's private ones included, for an admin's screens; + it is refused to anybody who is not an admin of the organization. A + missing cursor starts at the first page and nextCursor null ends the + list. + security: + - webSession: [] + - appOAuth: [bot-agents:read] + - apiKey: [] + parameters: + - name: scope + in: query + description: >- + Whose agents: caller, the agents the caller can see; organization, + every agent in the organization, for an admin of it only. + schema: + type: string + enum: [caller, organization] + default: caller + - $ref: './common.yaml#/components/parameters/Limit' + - $ref: './common.yaml#/components/parameters/Cursor' + responses: + '200': + description: One page of agents. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentPage' + examples: + lastPage: + $ref: '#/components/examples/BotAgentPageLast' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + post: + tags: [Agents] + operationId: createBotAgent + summary: Add an agent + description: >- + Add an agent for Bots to hand work to. kind openbot runs inside + OpenBot, on the model given or the organization's default. kind + address runs at an AG-UI address, which the server checks before + saving; a key, when given, is stored encrypted and never returned. + Anybody may add a private agent, for their own Bots; only an admin of + the organization may add a public one, which every member's Bots may + use. A repeated request with the same Idempotency-Key and body returns + the first result. + security: + - webSession: [] + - appOAuth: [bot-agents:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBotAgentRequest' + examples: + openbot: + summary: OpenBot's own agent, on a model of its own. + value: + name: Researcher + description: Deep research on the web and in the person's apps, with sources. + visibility: public + kind: openbot + model: null + address: + summary: An agent somebody runs themselves, behind a key. + value: + name: Pipeline analyst + description: Reads the sales pipeline and forecasts the quarter. + visibility: private + kind: address + endpoint: https://agents.example.com/ag-ui + auth: + header: Authorization + value: Bearer example-key + harness: langgraph + skills: + - name: Forecast + description: Forecasts the quarter from the open deals. + examples: [What will we close this quarter?] + responses: + '201': + description: The agent was added. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + Location: + description: The new agent's address. + schema: + type: string + example: /api/v2/organizations/default/bot-agents/bag_4f7c1e2a9d0b4c63 + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + created: + $ref: '#/components/examples/CreatedBotAgent' + '400': + $ref: '#/components/responses/InvalidBotAgent' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotAgentId' + get: + tags: [Agents] + operationId: getBotAgent + summary: Read one agent + description: >- + Return one agent the caller can see. An agent that does not exist, was + deleted, or is private to somebody else is not found. + security: + - webSession: [] + - appOAuth: [bot-agents:read] + - apiKey: [] + responses: + '200': + description: The agent. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + openbot: + $ref: '#/components/examples/OpenBotAgent' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + patch: + tags: [Agents] + operationId: updateBotAgent + summary: Change an agent + description: >- + Replace an agent's name, description and visibility, which are all + required, and change any optional field that is present. An absent + endpoint, key, model or skills leaves that setting as it is, so an edit + to a name never drops a key. Only whoever may manage the agent may + change it: its owner for a private one, an admin for a public one. + Only an admin may make an agent public. kind cannot change. Every Bot + that uses the agent runs on the change from its next turn. + security: + - webSession: [] + - appOAuth: [bot-agents:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateBotAgentRequest' + examples: + rename: + value: + name: Research desk + description: Deep research on the web and in the person's apps, with sources. + visibility: public + responses: + '200': + description: The changed agent. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + renamed: + $ref: '#/components/examples/CreatedBotAgent' + '400': + $ref: '#/components/responses/InvalidBotAgent' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + delete: + tags: [Agents] + operationId: deleteBotAgent + summary: Delete an agent + description: >- + Delete an agent and retire its key and callback token. It is taken off + every Bot that may use it. Refused, with BOT_AGENT_IN_USE, while it is + the only agent of any Bot, deleted Bots aside: give that Bot another + agent first. The refusal names those Bots the caller can see and + only counts the rest. Only whoever may manage the agent may delete it. Task + threads it worked in stay readable. An agent that is already deleted + is not found. + security: + - webSession: [] + - appOAuth: [bot-agents:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '204': + description: The agent was deleted. + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: '#/components/responses/BotAgentInUse' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}/issue-callback-token: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotAgentId' + post: + tags: [Agents] + operationId: issueBotAgentCallbackToken + summary: Issue an agent's callback token + description: >- + Give an agent at an address a new credential for calling OpenBot's + tools back, and return it this once: it is never returned again, and + the audit trail records that one was issued, never what it is. Issuing + one for an agent that has one replaces it, which is how a leaked token + is retired. A call made with it is allowed only for a run of a Bot + that may use this agent, as the person that run is for. Only whoever + may manage the agent may issue one. An agent that runs inside OpenBot, + or at an address OpenBot runs itself, needs none and is refused. + security: + - webSession: [] + - appOAuth: [bot-agents:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '200': + description: The new token, shown once. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentCallbackToken' + examples: + issued: + $ref: '#/components/examples/BotAgentCallbackTokenExample' + '400': + $ref: '#/components/responses/InvalidBotAgent' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}/revoke-callback-token: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/BotAgentId' + post: + tags: [Agents] + operationId: revokeBotAgentCallbackToken + summary: Revoke an agent's callback token + description: >- + Take away an agent's credential for calling OpenBot's tools back. It + still answers in a conversation; it can't reach anything outside one. + Only whoever may manage the agent may revoke it. Revoking a token that + is not there changes nothing. + security: + - webSession: [] + - appOAuth: [bot-agents:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '200': + description: The agent, with no callback token. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotAgentResponse' + examples: + revoked: + $ref: '#/components/examples/CreatedBotAgent' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/BotAgentForbidden' + '404': + $ref: '#/components/responses/BotAgentNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/bots/{botId}/delegation: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: './common.yaml#/components/parameters/BotId' + get: + tags: [Agents] + operationId: getBotDelegation + x-openbot-singleton: true + summary: Read a Bot's delegation + description: >- + Return how a Bot the caller can see works: on its own agent (mode + self, every Bot made before agents were a list), or handing work to + the agents it may use (mode orchestrate). The first agent is its + default: a Bot in mode self runs on it, and a Bot in mode orchestrate + hands it work the Bot names no agent for and every run nobody is + waiting on (a routine, a check-in, a goal, another Bot's hand-off, a + group conversation). Whoever uses a Bot uses its agents: an agent that + is private to the Bot's owner still does the work for everybody the + Bot is shared with, and to anybody else it is named Private agent, + with its description withheld. An agent that was deleted, or that the + Bot's owner can no longer use, is listed with available false, and + the Bot hands it nothing. + security: + - webSession: [] + - appOAuth: [bots:read] + - apiKey: [] + responses: + '200': + description: The Bot's delegation. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotDelegation' + examples: + self: + $ref: '#/components/examples/SelfBotDelegation' + orchestrate: + $ref: '#/components/examples/OrchestratingBotDelegation' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: './common.yaml#/components/responses/BotNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + put: + tags: [Agents] + operationId: replaceBotDelegation + summary: Set a Bot's delegation + description: >- + Replace how a Bot works. Mode self takes exactly one agent, which the + Bot runs on with its apps, as every Bot did before agents were a list. + Mode orchestrate takes one to twenty agents, in order, the first being + the default: the Bot then answers on its own model with only the tools + for replying, reacting, finding a task's thread and handing work to an + agent, plus reading the person's memory, and each agent works with the + Bot's apps as the person who asked. model and effort are the Bot's own + when it orchestrates, one the model catalogue offers, or null for the + organization's default; they are ignored in mode self. instructions + steer how it hands work out and answers, and are read only in mode + orchestrate. Every agent named must be one the caller can see, or one + the Bot already has. Only + whoever may manage the Bot may change it, and a Bot that comes with + OpenBot cannot be changed. + security: + - webSession: [] + - appOAuth: [bots:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReplaceBotDelegationRequest' + examples: + orchestrate: + value: + mode: orchestrate + model: null + effort: null + instructions: Hand research to Researcher and anything about the pipeline to Pipeline analyst. Answer greetings yourself. + agentIds: [bag_4f7c1e2a9d0b4c63, bag_9a2d7e1c3b5f4086] + responses: + '200': + description: The Bot's delegation after the change. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/BotDelegation' + examples: + orchestrate: + $ref: '#/components/examples/OrchestratingBotDelegation' + '400': + $ref: '#/components/responses/InvalidBotDelegation' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/BotForbidden' + '404': + $ref: './common.yaml#/components/responses/BotNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' +components: + parameters: + BotAgentId: + name: botAgentId + in: path + required: true + description: The agent's id. + schema: + type: string + minLength: 1 + maxLength: 200 + pattern: \S + example: bag_4f7c1e2a9d0b4c63 + schemas: + BotAgentKind: + type: string + enum: [openbot, address] + description: >- + openbot: runs inside OpenBot. address: runs at an AG-UI address, + somebody's own or a framework OpenBot runs itself. + BotAgentVisibility: + type: string + enum: [public, private] + description: >- + public: every member's Bots may use it, and only an admin may make one. + private: only its owner's Bots may use it. + BotAgentSkill: + type: object + description: >- + One thing the agent is good at, in the shape of an A2A Agent Card's + skill. A Bot reads its agents' skills when it decides which to hand + work to. + additionalProperties: false + required: [name, description] + properties: + name: + type: string + minLength: 1 + maxLength: 80 + pattern: \S + description: The skill's name, 1 to 80 characters once trimmed. + description: + type: string + minLength: 1 + maxLength: 500 + pattern: \S + description: What it does, 1 to 500 characters once trimmed. + examples: + type: array + maxItems: 5 + description: Up to five things a person might ask for that it handles. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: \S + BotAgent: + type: object + description: >- + An agent as the caller sees it. canManage, mine and builtIn are the + server's verdicts for this caller; a client renders them and never + recomputes them. No secret is ever part of an agent: hasAuth and + hasCallbackToken say whether one is set. + required: + - id + - name + - description + - kind + - visibility + - endpoint + - model + - skills + - hasAuth + - hasCallbackToken + - builtIn + - canManage + - mine + - botCount + - createdAt + - updatedAt + properties: + id: + type: string + description: The agent's id. + name: + type: string + description: What the agent is called. + description: + type: string + description: >- + What it is good at, in its owner's words. A Bot reads it when it + decides which agent to hand work to. + kind: + $ref: '#/components/schemas/BotAgentKind' + visibility: + $ref: '#/components/schemas/BotAgentVisibility' + endpoint: + type: [string, 'null'] + description: >- + The AG-UI address it runs at, as it was stored. Null for an agent + that runs inside OpenBot. + framework: + type: string + description: >- + What runs it, by the name a person reads ("LangChain", "OpenBot"). + Absent when OpenBot doesn't know. + model: + type: [string, 'null'] + description: >- + The model it runs on, for an agent whose model is OpenBot's to + choose. Null for the organization's default, or for an agent that + picks its own. + skills: + type: array + items: + $ref: '#/components/schemas/BotAgentSkill' + hasAuth: + type: boolean + description: Whether a key is set for its address. Never the key. + hasCallbackToken: + type: boolean + description: >- + Whether it holds a credential for calling OpenBot's tools back. + Never the credential. + builtIn: + type: boolean + description: >- + Whether OpenBot runs it, inside OpenBot or at an address OpenBot + started, so it needs no callback token of its own. + canManage: + type: boolean + description: Whether the caller may change and delete it. + mine: + type: boolean + description: Whether the caller added it. + botCount: + type: integer + minimum: 0 + description: >- + How many of the Bots the caller can see may use it, deleted Bots + aside. A count only: which Bots is not said. With + scope=organization, every Bot in the organization. + createdAt: + type: string + format: date-time + description: When it was added. + updatedAt: + type: string + format: date-time + description: When it last changed. + BotAgentPage: + type: object + required: [agents, nextCursor] + properties: + agents: + type: array + items: + $ref: '#/components/schemas/BotAgent' + nextCursor: + type: [string, 'null'] + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: >- + Pass as cursor for the next page. Null ends the list. Written in + URL-safe base64, the only form the cursor parameter accepts. + BotAgentResponse: + type: object + required: [agent] + properties: + agent: + $ref: '#/components/schemas/BotAgent' + BotAgentKey: + type: object + description: >- + A key the agent's address sits behind. Write-only: stored encrypted and + never returned. A blank value sets no key. + additionalProperties: false + required: [value] + properties: + header: + type: string + maxLength: 200 + pattern: ^[A-Za-z0-9-]*$ + description: The header it is sent in. Blank or absent means Authorization. + value: + type: string + maxLength: 8000 + writeOnly: true + description: The header's value. + BotAgentName: + type: string + minLength: 1 + maxLength: 80 + pattern: \S + description: What the agent is called, 1 to 80 characters once trimmed. + BotAgentDescription: + type: string + minLength: 1 + maxLength: 1000 + pattern: \S + description: >- + What it is good at, 1 to 1000 characters once trimmed. A Bot reads it + when it decides which agent to hand work to, so say what to send it. + BotAgentEndpoint: + type: string + description: >- + The AG-UI address it runs at: an absolute http or https address. An + address that fits can still be refused: the server refuses one this + organization may not reach, and one that does not answer a real AG-UI + run. + maxLength: 2048 + format: uri + pattern: ^[Hh][Tt][Tt][Pp][Ss]?:// + BotAgentModel: + type: [string, 'null'] + minLength: 1 + maxLength: 500 + pattern: \S + description: >- + A model the catalogue offers, or null for the organization's default. + Read only for an agent whose model is OpenBot's to choose. + BotAgentSkills: + type: array + maxItems: 20 + description: Up to twenty things it is good at. Absent on a change leaves them as they are. + items: + $ref: '#/components/schemas/BotAgentSkill' + BotAgentHarness: + type: string + description: >- + The framework an agent at an address is built on, by its id in + OpenBot's harness list (shared/harnesses.json). Empty means none was + named. Kept only for kind address. + enum: + - '' + - crewai + - llamaindex + - agno + - langgraph + - google-adk + - antigravity + - pydantic-ai + - microsoft-agent-framework + - claude-agent-sdk + - strands + - ag2 + - langroid + - mastra + CreateBotAgentRequest: + type: object + description: >- + A new agent. endpoint is required for kind address and refused for + kind openbot. + additionalProperties: false + required: [name, description, visibility, kind] + properties: + name: + $ref: '#/components/schemas/BotAgentName' + description: + $ref: '#/components/schemas/BotAgentDescription' + visibility: + $ref: '#/components/schemas/BotAgentVisibility' + kind: + $ref: '#/components/schemas/BotAgentKind' + endpoint: + $ref: '#/components/schemas/BotAgentEndpoint' + auth: + $ref: '#/components/schemas/BotAgentKey' + harness: + $ref: '#/components/schemas/BotAgentHarness' + model: + $ref: '#/components/schemas/BotAgentModel' + skills: + $ref: '#/components/schemas/BotAgentSkills' + UpdateBotAgentRequest: + type: object + description: An agent's fields after the change. Absent optional fields stay as they are. + additionalProperties: false + required: [name, description, visibility] + properties: + name: + $ref: '#/components/schemas/BotAgentName' + description: + $ref: '#/components/schemas/BotAgentDescription' + visibility: + $ref: '#/components/schemas/BotAgentVisibility' + endpoint: + $ref: '#/components/schemas/BotAgentEndpoint' + auth: + $ref: '#/components/schemas/BotAgentKey' + model: + $ref: '#/components/schemas/BotAgentModel' + skills: + $ref: '#/components/schemas/BotAgentSkills' + BotAgentCallbackToken: + type: object + required: [token] + properties: + token: + type: string + minLength: 1 + description: >- + The agent's credential for calling OpenBot's tools back. Returned + this once and never again. + BotDelegationMode: + type: string + enum: [self, orchestrate] + description: >- + self: the Bot runs on its one agent with its apps. orchestrate: the + Bot answers on its own model and hands work to the agents it may use. + BotDelegationAgent: + type: object + description: One agent a Bot may use, as the caller sees it. + required: [id, name, description, kind, available] + properties: + id: + type: string + description: The agent's id. + name: + type: string + description: >- + What the agent is called. An agent private to somebody other than + the caller is named Private agent. + description: + type: string + description: What it is good at. Empty for an agent private to somebody other than the caller. + kind: + $ref: '#/components/schemas/BotAgentKind' + framework: + type: string + description: What runs it, by the name a person reads. Absent when OpenBot doesn't know. + available: + type: boolean + description: >- + Whether the Bot may still hand it work: false once the agent is + deleted, or private to somebody other than the Bot's owner. + BotDelegation: + type: object + description: How a Bot works, and the agents it may use, the first being its default. + required: [botId, mode, model, effort, instructions, agents, canManage] + properties: + botId: + type: string + description: The Bot's id. + mode: + $ref: '#/components/schemas/BotDelegationMode' + model: + type: [string, 'null'] + description: >- + The model the Bot answers on when it orchestrates, or null for the + organization's default. + effort: + type: [string, 'null'] + description: How hard it thinks when it orchestrates, or null for the model's own. + instructions: + type: string + description: >- + How it hands work out and answers when it orchestrates. May be + empty. Empty for a caller who can't change the Bot, since it can + name an agent private to its owner. + agents: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/BotDelegationAgent' + canManage: + type: boolean + description: Whether the caller may change it. + ReplaceBotDelegationRequest: + type: object + additionalProperties: false + required: [mode, model, effort, instructions, agentIds] + properties: + mode: + $ref: '#/components/schemas/BotDelegationMode' + model: + type: [string, 'null'] + minLength: 1 + maxLength: 500 + pattern: \S + description: A model the catalogue offers, or null for the default. Trimmed. + effort: + type: [string, 'null'] + minLength: 1 + maxLength: 40 + pattern: \S + description: An effort the model takes, or null for its own. Trimmed, and read in lower case. + instructions: + type: string + maxLength: 4000 + description: How it hands work out and answers, up to 4000 characters. May be empty. + agentIds: + type: array + minItems: 1 + maxItems: 20 + uniqueItems: true + description: >- + The agents it may use, in order, the first being its default. + Exactly one in mode self. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: \S + responses: + InvalidBotAgent: + description: >- + A field is missing or out of bounds, kind and endpoint don't agree, + the address is one this organization may not reach or did not answer + a real AG-UI run, the model is not one the catalogue offers, or the + agent runs inside OpenBot and so takes no callback token. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + description: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: Say what this agent is good at, so your Bots know what to send it. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + unreachable: + value: + type: https://open.bot/errors/bot-agent-unreachable + title: Couldn't reach that agent. + status: 400 + detail: Couldn't reach an agent at that address. Check the address and its key, then try again. + code: BOT_AGENT_UNREACHABLE + category: validation + retryable: false + requestId: req_example + traceId: trace_example + BotAgentForbidden: + description: >- + The caller may not manage this agent, or only an admin may make an + agent public. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + notYours: + value: + type: https://open.bot/errors/permission-denied + title: You can't manage this agent. + status: 403 + detail: You can't manage this agent. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + publicAdminOnly: + value: + type: https://open.bot/errors/permission-denied + title: Only an admin can share an agent with everyone. + status: 403 + detail: Only an admin can share an agent with everyone. Keep it private to use it with your own Bots. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + BotAgentNotFound: + description: >- + The agent does not exist, was deleted, or is not visible to the + caller, or the organization is not. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + missing: + value: + type: https://open.bot/errors/bot-agent-not-found + title: Agent not found. + status: 404 + detail: Couldn't find that agent. + code: BOT_AGENT_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + BotAgentInUse: + description: >- + The agent is the only agent of a Bot, or a repeated request with the + same Idempotency-Key had a different body. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + onlyAgent: + value: + type: https://open.bot/errors/bot-agent-in-use + title: A Bot runs on this agent alone. + status: 409 + detail: Quote Checker and 1 other Bot run on this agent alone. Give them another agent first, then delete this one. + code: BOT_AGENT_IN_USE + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + InvalidBotDelegation: + description: >- + A field is missing or out of bounds, mode self names other than one + agent, an agent named is not one the caller can see, or the model or + effort is not one the catalogue offers. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + selfTakesOne: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A Bot that works on its own runs on one agent. Turn on handing work to agents to choose more. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + unknownAgent: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: Couldn't find one of those agents. Choose from the agents you can see. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + examples: + BotAgentPageLast: + summary: The last page. + value: + agents: + - id: bag_0c51d9e3a7f24b18 + name: OpenBot + description: OpenBot's own agent, with every app and component the Bot may use. + kind: openbot + visibility: public + endpoint: null + framework: OpenBot + model: null + skills: [] + hasAuth: false + hasCallbackToken: false + builtIn: true + canManage: false + mine: false + botCount: 4 + createdAt: '2026-11-16T09:00:00Z' + updatedAt: '2026-11-16T09:00:00Z' + nextCursor: null + OpenBotAgent: + summary: OpenBot's own agent. + value: + agent: + id: bag_0c51d9e3a7f24b18 + name: OpenBot + description: OpenBot's own agent, with every app and component the Bot may use. + kind: openbot + visibility: public + endpoint: null + framework: OpenBot + model: null + skills: [] + hasAuth: false + hasCallbackToken: false + builtIn: true + canManage: false + mine: false + botCount: 4 + createdAt: '2026-11-16T09:00:00Z' + updatedAt: '2026-11-16T09:00:00Z' + CreatedBotAgent: + summary: An agent a person added at their own address. + value: + agent: + id: bag_4f7c1e2a9d0b4c63 + name: Pipeline analyst + description: Reads the sales pipeline and forecasts the quarter. + kind: address + visibility: private + endpoint: https://agents.example.com/ag-ui + framework: LangChain + model: null + skills: + - name: Forecast + description: Forecasts the quarter from the open deals. + examples: [What will we close this quarter?] + hasAuth: true + hasCallbackToken: false + builtIn: false + canManage: true + mine: true + botCount: 0 + createdAt: '2026-11-16T09:30:00Z' + updatedAt: '2026-11-16T09:30:00Z' + BotAgentCallbackTokenExample: + summary: A new token. + value: + token: obot_agt_7f3a9c2e5d1b4f60a8e2c9d4b1f7e3a6c0d9 + SelfBotDelegation: + summary: A Bot that runs on its own agent, as every Bot did before agents were a list. + value: + botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21 + mode: self + model: null + effort: null + instructions: '' + agents: + - id: bag_0c51d9e3a7f24b18 + name: OpenBot + description: OpenBot's own agent, with every app and component the Bot may use. + kind: openbot + framework: OpenBot + available: true + canManage: true + OrchestratingBotDelegation: + summary: A Bot that hands work to two agents. + value: + botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21 + mode: orchestrate + model: null + effort: null + instructions: Hand research to Researcher and anything about the pipeline to Pipeline analyst. Answer greetings yourself. + agents: + - id: bag_4f7c1e2a9d0b4c63 + name: Researcher + description: Deep research on the web and in the person's apps, with sources. + kind: openbot + framework: OpenBot + available: true + - id: bag_9a2d7e1c3b5f4086 + name: Pipeline analyst + description: Reads the sales pipeline and forecasts the quarter. + kind: address + framework: LangChain + available: true + canManage: true diff --git a/api/openapi/common.yaml b/api/openapi/common.yaml index 5ef3decf22..46d3095bf2 100644 --- a/api/openapi/common.yaml +++ b/api/openapi/common.yaml @@ -112,6 +112,7 @@ tags: - { name: Product events, description: "What a person did with a Bot's answer, seen on screen or copied, counted so OpenBot knows which answers people use. Best effort: a client never waits on one." } - { name: Learning, description: "Automatic learning: the skills Learning proposed, the evidence behind them, approving and rejecting them, and its runs, in the organization's spaces and each person's own; which space each Bot learns into, who reviews what people's recordings propose, each person's sharing choices, requests to share a skill with every Bot, and the skills delivered to Bots." } - { name: Memory, description: "The facts a person's Bots remember about them, and the app actions those facts are read in from. Each person's are theirs alone: an administrator can't read them either." } + - { name: Agents, description: "The agents an organization's Bots hand work to: OpenBot's own, a framework OpenBot runs, or an agent somebody runs at its own address. An administrator adds the organization's, and anybody may add a private one for their own Bots. A Bot's delegation says whether it works on one agent or hands work to several, and which." } paths: /api/v2/organizations/{organizationId}/reactions: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1reactions' } /api/v2/organizations/{organizationId}/bots: { $ref: './bots.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots' } @@ -175,9 +176,11 @@ paths: /api/v2/organizations/{organizationId}/conversation-threads/{threadId}: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1conversation-threads~1{threadId}' } /api/v2/organizations/{organizationId}/tasks: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks' } /api/v2/organizations/{organizationId}/tasks/{taskId}: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks~1{taskId}' } + /api/v2/organizations/{organizationId}/tasks/{taskId}/turns: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks~1{taskId}~1turns' } /api/v2/organizations/{organizationId}/tasks/{taskId}/resolve: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks~1{taskId}~1resolve' } /api/v2/organizations/{organizationId}/tasks/{taskId}/reopen: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks~1{taskId}~1reopen' } /api/v2/organizations/{organizationId}/tasks/{taskId}/retry: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks~1{taskId}~1retry' } + /api/v2/organizations/{organizationId}/tasks/{taskId}/stop: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1tasks~1{taskId}~1stop' } /api/v2/organizations/{organizationId}/transcriptions: { $ref: './conversations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1transcriptions' } /api/v2/organizations/{organizationId}/credentials: { $ref: './model-connections.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1credentials' } /api/v2/organizations/{organizationId}/credentials/{credentialId}/revoke: { $ref: './model-connections.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1credentials~1{credentialId}~1revoke' } @@ -447,6 +450,11 @@ paths: /api/v2/organizations/{organizationId}/people/{personId}/memory-sources/{memorySourceId}: { $ref: './memory.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1memory-sources~1{memorySourceId}' } /api/v2/organizations/{organizationId}/people/{personId}/memory-sources/{memorySourceId}/sync: { $ref: './memory.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1memory-sources~1{memorySourceId}~1sync' } /api/v2/organizations/{organizationId}/bots/{botId}/memory-source-tools: { $ref: './memory.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1memory-source-tools' } + /api/v2/organizations/{organizationId}/bot-agents: { $ref: './agents.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bot-agents' } + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}: { $ref: './agents.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bot-agents~1{botAgentId}' } + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}/issue-callback-token: { $ref: './agents.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bot-agents~1{botAgentId}~1issue-callback-token' } + /api/v2/organizations/{organizationId}/bot-agents/{botAgentId}/revoke-callback-token: { $ref: './agents.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bot-agents~1{botAgentId}~1revoke-callback-token' } + /api/v2/organizations/{organizationId}/bots/{botId}/delegation: { $ref: './agents.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1delegation' } components: securitySchemes: webSession: @@ -605,6 +613,8 @@ components: learning:write: Approve and reject what Learning proposed and start Learning in the signed-in person's own spaces, change their Learning choices, and for an administrator change the organization's Learning settings and decide sharing requests. memories:read: Read the signed-in person's memories and memory sources. memories:write: Write, change and forget the signed-in person's memories, and add, change, sync and remove their memory sources. + bot-agents:read: Read the agents the signed-in person's Bots may hand work to, and for an administrator every agent in the organization. + bot-agents:write: Add, change and delete the signed-in person's own agents and their callback tokens, and for an administrator the organization's. apiKey: type: http scheme: bearer diff --git a/api/openapi/conversations.yaml b/api/openapi/conversations.yaml index e9696f26f9..713a9ee245 100644 --- a/api/openapi/conversations.yaml +++ b/api/openapi/conversations.yaml @@ -1303,6 +1303,58 @@ paths: $ref: '#/components/responses/ServiceUnavailable' default: $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/tasks/{taskId}/turns: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TaskId' + get: + tags: + - Tasks + operationId: listTaskTurns + summary: List a task's turns + description: "Return one page of the turns a task has finished, oldest + first: each time its Bot worked on something it was asked in the + task's conversation, the Bot's brief or a line the person said there. + Each says how long the Bot worked on it, counting only the time its + runs took, never the time it waited on the person, and which model + answered. A turn still running is not listed until it ends. Another + person's task is not found. A missing cursor starts at the first page + and nextCursor null ends the list." + security: + - webSession: [] + - appOAuth: + - tasks:read + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/Limit' + - $ref: './common.yaml#/components/parameters/Cursor' + responses: + '200': + description: One page of the task's turns. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskTurnPage' + examples: + example: + $ref: '#/components/examples/TaskTurnPageExample' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TaskNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + '503': + $ref: '#/components/responses/ServiceUnavailable' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/tasks/{taskId}/resolve: parameters: - $ref: './common.yaml#/components/parameters/OrganizationId' @@ -1445,6 +1497,57 @@ paths: $ref: '#/components/responses/ServiceUnavailable' default: $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/tasks/{taskId}/stop: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TaskId' + post: + tags: + - Tasks + operationId: stopTask + summary: Stop a task + description: Stop the task's work, as Stop in its conversation does. A + step it is in the middle of is cut off; the steps it finished stay done, + and its conversation and the one that asked for it say how far it got. + What it waits on the person for is no longer asked. Only a task that is + working or waiting on the person can be stopped. The answer is the task + as it stands now, which is stopped. + security: + - webSession: [] + - appOAuth: + - tasks:write + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '200': + description: The task as it stands now. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + example: + $ref: '#/components/examples/TaskResponseExample' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TaskNotFound' + '409': + $ref: '#/components/responses/TaskConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + '503': + $ref: '#/components/responses/ServiceUnavailable' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/transcriptions: parameters: - $ref: './common.yaml#/components/parameters/OrganizationId' @@ -2388,6 +2491,24 @@ components: botId: type: string description: The Bot doing it. + agent: + type: [object, 'null'] + description: >- + The agent doing the work, when the Bot handed it to one of the + agents it may use. Null for a task the Bot does itself, which is + every task before agents were a list. Absent from a server that + does not name it. + additionalProperties: false + required: [id, name] + properties: + id: + type: string + description: The agent's id. + name: + type: string + description: >- + What the agent is called. An agent private to somebody other + than the caller is named Private agent. conversationId: type: string description: The task's own conversation, where the person reads it and replies. @@ -2526,6 +2647,59 @@ components: pattern: ^[A-Za-z0-9_-]+$ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + TaskTurn: + type: object + description: One finished turn of a task's work, answering one thing it was asked in its conversation. + required: + - askId + - startedAt + - endedAt + - workedSeconds + - runs + - model + properties: + askId: + type: string + description: The id of the message the turn answered, as the conversation's history names it. + startedAt: + type: string + format: date-time + description: When its first run began. + endedAt: + type: string + format: date-time + description: When its last run ended. + workedSeconds: + type: integer + minimum: 0 + description: How long its runs took, added up. A wait on the person between two runs (an approval, a question) is not counted. + runs: + type: integer + minimum: 1 + description: How many runs it took. More than one when it stopped for the person and carried on after. + model: + type: + - string + - 'null' + description: The model its last run used. Null when the Bot chooses its own model and did not name it. + TaskTurnPage: + type: object + required: + - turns + - nextCursor + properties: + turns: + type: array + items: + $ref: '#/components/schemas/TaskTurn' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written + in URL-safe base64, the only form the cursor parameter accepts. TaskResponse: type: object required: @@ -3106,6 +3280,9 @@ components: TaskResponseExample: summary: "A task ready to read." value: {"task": {"id": "7c2d6b1f-6f10-4a53-9d51-5f0d6c0e2f1a", "botId": "general-assistant", "conversationId": "5f0d6c0e-2f1a-4a53-9d51-6f3d6b1f6f10", "threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "title": "Reply to Sam about the spec", "why": "Sam asked for the spec by Friday.", "origin": "check_in", "suggestionId": "0b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21", "sourceApp": "Gmail", "sourceLink": null, "originConversationId": null, "status": "ready_for_review", "failure": null, "failedAt": null, "stoppedAt": null, "next": "Read the draft and send it.", "workingSince": null, "lastActivityAt": "2026-11-14T09:05:00.000Z", "resolvedAt": null, "createdAt": "2026-11-14T09:00:00.000Z", "updatedAt": "2026-11-14T09:05:00.000Z"}} + TaskTurnPageExample: + summary: "One turn: the Bot's brief, worked on for 52 seconds." + value: {"turns": [{"askId": "3a1c9e2b-5d40-4f7a-8b61-0e9d2c4f7a13", "startedAt": "2026-11-14T09:00:02.000Z", "endedAt": "2026-11-14T09:00:54.000Z", "workedSeconds": 52, "runs": 1, "model": "gpt-5.1"}], "nextCursor": null} TranscriptionExample: summary: "What was said." value: {"text": "Remind me to send the forecast on Friday."} diff --git a/app/src/components/agents/new-bot-sheet.tsx b/app/src/components/agents/new-bot-sheet.tsx index 59fe1812e9..5ecf15a0d9 100644 --- a/app/src/components/agents/new-bot-sheet.tsx +++ b/app/src/components/agents/new-bot-sheet.tsx @@ -65,11 +65,11 @@ import { type GiveableApp, giveableAppsQueryOptions, } from "@/lib/app-access/queries"; +import { appsQueryOptions } from "@/lib/apps/queries"; import { isComposing } from "@/lib/composing"; import { ALWAYS_ON_APP } from "@/lib/connections/rows"; import { deploymentCapabilitiesQueryOptions } from "@/lib/deployment/queries"; import { myCapabilitiesQueryOptions } from "@/lib/enterprise/queries"; -import { appsQueryOptions } from "@/lib/apps/queries"; import { type PluginServer, pluginKeys } from "@/lib/plugins/queries"; import { cn } from "@/lib/utils"; import { queryClient } from "@/query-client"; @@ -127,14 +127,18 @@ type Step = (typeof STEPS)[number]; * The framework is kept for its connection instructions and default role description. Every framework is reached the same way and stored the same way — an AG-UI address — * so the server never hears which was picked. */ -type Runtime = { kind: "builtin" } | { kind: "managed"; harness: string }; +export type Runtime = + | { kind: "builtin" } + | { kind: "managed"; harness: string }; /** * The framework as the API names it, or undefined for "An agent you already run" (`byo-url`), which * names none. The API lists the same ids as the harness catalogue, and api/openapi-harnesses.test.ts * fails if the two drift apart. */ -function declaredFramework(id: string): CreateBotRequestHarness | undefined { +export function declaredFramework( + id: string, +): CreateBotRequestHarness | undefined { const known: readonly string[] = Object.values(CreateBotRequestHarness); return id !== "" && known.includes(id) ? (id as CreateBotRequestHarness) @@ -938,7 +942,7 @@ function IsolatedOption({ * Filled rather than outlined, so the list reads as a set of things to pick and not as a stack of * cards. The border is there but transparent until chosen, so choosing one never shifts the rows. */ -const OPTION_CLASSES = +export const OPTION_CLASSES = "flex w-full items-center gap-3 rounded-lg border border-transparent bg-muted/50 p-3 text-left transition-colors hover:bg-muted disabled:pointer-events-none disabled:opacity-50 aria-pressed:border-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"; /** @@ -947,7 +951,11 @@ const OPTION_CLASSES = * new question rather than the control on the previous screen. The sheet body scrolls; * an inner scroller would give this list a second scrollbar. */ -function RuntimeStep({ onChoose }: { onChoose: (runtime: Runtime) => void }) { +export function RuntimeStep({ + onChoose, +}: { + onChoose: (runtime: Runtime) => void; +}) { const heading = useRef(null); useEffect(() => heading.current?.focus(), []); @@ -996,7 +1004,7 @@ function RuntimeStep({ onChoose }: { onChoose: (runtime: Runtime) => void }) { * from there, which is the one thing the browser cannot tell. Why it could not be reached arrives as * this field's error. */ -function EndpointStep({ +export function EndpointStep({ harness, endpoint, secret, diff --git a/app/src/components/approvals/inline-approval.tsx b/app/src/components/approvals/inline-approval.tsx index dee1c81416..33925f4e43 100644 --- a/app/src/components/approvals/inline-approval.tsx +++ b/app/src/components/approvals/inline-approval.tsx @@ -1,11 +1,9 @@ import { offersStandingRule } from "@openbot/shared/standing-rule"; -import { - approvalPhrase, - PRIVATE_SHARE_TOOL_REF, -} from "@openbot/shared/tool-name"; +import { approvalPhrase } from "@openbot/shared/tool-name"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; import { AnimatePresence, motion, useReducedMotion } from "motion/react"; import { type ReactNode, useState } from "react"; +import { shareOf, ShareText } from "@/components/approvals/share-details"; import { DecisionCard } from "@/components/decisions/decision-card"; import type { Tone } from "@/components/gallery/frame"; import { @@ -107,32 +105,8 @@ export function InlineApproval({ ]; // In the words the step and Activity use for the same action: "Save a file todo.txt in share". const title = request ? approvalPhrase(request.action) : ""; - // A share shows what it would send, so the person sees what leaves the conversation. - const share = - request?.action.toolRef === PRIVATE_SHARE_TOOL_REF - ? ((request.action.args ?? {}) as { - preview?: unknown; - audience?: unknown; - handOff?: unknown; - }) - : undefined; - const shared = share?.preview; - /* - * Handed to another person's Bot, the card says who reads it. When the person also asks before - * changes, this one card is both asks, so it says it hands the work over and shares the text. - */ - const handedTo = - typeof share?.handOff === "string" - ? share.handOff - : (request?.action.target as { kind?: unknown } | undefined)?.kind === - "handoff" && typeof share?.audience === "string" - ? share.audience - : undefined; - const shareCaption = handedTo - ? typeof share?.handOff === "string" - ? `${handedTo} belongs to someone else, so this also shares the text below with them.` - : `${handedTo} belongs to someone else, so they can read the text below.` - : undefined; + // A share shows who reads it and what it would send, so the person sees what leaves the conversation. + const share = request ? shareOf(request.action) : null; return ( <> {/* The card leaves by folding away; what is left behind is the tool's own line. */} @@ -159,7 +133,7 @@ export function InlineApproval({ } caption={ request.action.policy?.reason ?? - shareCaption ?? + share?.caption ?? (handOff ? "This one is yours to do." : undefined) } error={decision.error?.message ?? null} @@ -175,14 +149,7 @@ export function InlineApproval({ submitting={decision.isPending} title={title.charAt(0).toUpperCase() + title.slice(1)} > - {typeof shared === "string" && shared.trim() ? ( -
- {shared} -
- ) : null} + {share?.text ? : null} ) : null} diff --git a/app/src/components/approvals/share-details.tsx b/app/src/components/approvals/share-details.tsx new file mode 100644 index 0000000000..cc2addd03d --- /dev/null +++ b/app/src/components/approvals/share-details.tsx @@ -0,0 +1,109 @@ +import { PRIVATE_SHARE_TOOL_REF } from "@openbot/shared/tool-name"; +import { useCallback, useState } from "react"; +import { cn } from "@/lib/utils"; + +/** An approval as much as a share's details read: what it is, where it goes, what it sends. */ +type ShareAction = { toolRef: string; target?: unknown; args?: unknown }; + +/** + * What a request to share something private says to the person: who reads it, as one sentence, + * and the text itself. Null for any other request. + * + * Handed to another person's Bot, the sentence says who reads it. When the person also asks before + * changes, one card is both asks, so it says it hands the work over and shares the text. + */ +export function shareOf( + action: ShareAction, +): { caption: string | undefined; text: string | undefined } | null { + if (action.toolRef !== PRIVATE_SHARE_TOOL_REF) return null; + const share = (action.args ?? {}) as { + preview?: unknown; + audience?: unknown; + handOff?: unknown; + }; + const handedTo = + typeof share.handOff === "string" + ? share.handOff + : (action.target as { kind?: unknown } | undefined)?.kind === "handoff" && + typeof share.audience === "string" + ? share.audience + : undefined; + return { + caption: handedTo + ? typeof share.handOff === "string" + ? `${handedTo} belongs to someone else, so this also shares the text below with them.` + : `${handedTo} belongs to someone else, so they can read the text below.` + : undefined, + text: + typeof share.preview === "string" && share.preview.trim() + ? share.preview + : undefined, + }; +} + +/** + * The text a share would send, whole. A short text is shown as it is. A long one is cut to a few + * lines and faded at the foot, with Show all to read the rest in place, as a step's output is in + * the conversation. Never a box that scrolls on its own: where scroll bars hide until used, the + * end of the text looked like the end of the box, and the person allowed words they never saw. + */ +export function ShareText({ text }: { text: string }) { + const [open, setOpen] = useState(false); + const [long, setLong] = useState(false); + const measure = useCallback((element: HTMLQuoteElement | null) => { + if (element) setLong(element.scrollHeight > element.clientHeight + 1); + }, []); + return ( +
+
+ {text} + {long && !open ? ( + + ) : null} +
+ {long ? ( + + ) : null} +
+ ); +} + +/** + * A share as a list row shows it under the request: the same sentence and text its card in the + * conversation shows, so the person reads the same thing in both places before they answer. + */ +export function ShareDetails({ + action, + className, +}: { + action: ShareAction; + className?: string; +}) { + const share = shareOf(action); + if (!share || (!share.caption && !share.text)) return null; + return ( +
+ {share.caption ? ( +

{share.caption}

+ ) : null} + {share.text ? : null} +
+ ); +} diff --git a/app/src/components/approvals/waiting.tsx b/app/src/components/approvals/waiting.tsx index 858e6af203..eaf238f1be 100644 --- a/app/src/components/approvals/waiting.tsx +++ b/app/src/components/approvals/waiting.tsx @@ -1,5 +1,9 @@ import { offersStandingRule } from "@openbot/shared/standing-rule"; -import { approvalDetails, approvalWords } from "@openbot/shared/tool-name"; +import { + approvalDetails, + approvalPhrase, + approvalWords, +} from "@openbot/shared/tool-name"; import { IconDots, IconHandStop, @@ -10,8 +14,13 @@ import { useMutation, useQuery } from "@tanstack/react-query"; import { useNavigate } from "@tanstack/react-router"; import { Fragment, type ReactNode, useState } from "react"; import { BotOrb } from "@/components/agents/bot-orb"; +import { ShareDetails, shareOf } from "@/components/approvals/share-details"; import { PageRows } from "@/components/layout/page-shell"; -import { BoardRow } from "@/components/needs-you/board-row"; +import { + BoardRow, + ROW_MENU_WIDTH, + RowMenu, +} from "@/components/needs-you/board-row"; import { Button } from "@/components/ui/button"; import { Dialog, @@ -24,6 +33,7 @@ import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, + DropdownMenuSeparator, DropdownMenuTrigger, } from "@/components/ui/dropdown-menu"; import { @@ -135,15 +145,21 @@ function QuestionRow({ /** * What an approval would send, a labelled line each: "Text: hello". Nothing when it sends nothing * the title has not said already, as a click does: its ref and snapshot are handles for the model. + * + * A share reads as its card in the conversation reads: who reads it, in a sentence, and the whole + * text. Its own fields (the audience's key, a count of recipients, the text's fingerprint) are the + * server's, and listed here as "Audience", "Recipients" and "Preview" they said less than the card. */ function ApprovalDetails({ - args, + action, className, }: { - args: unknown; + action: WaitingRequest["action"]; className?: string; }) { - const details = approvalDetails(args); + if (shareOf(action)) + return ; + const details = approvalDetails(action.args); if (details.length === 0) return null; return (
@@ -185,11 +203,14 @@ function RequestRow({ - {botName} wants to {words.action} + {botName} wants to{" "} + {share ? approvalPhrase(request.action) : words.action} - - {words.place} - + {share ? null : ( + + {words.place} + + )} {request.action.policy ? (

{request.action.policy.behaviour === "hand_off" @@ -198,7 +219,7 @@ function RequestRow({ {request.action.policy.reason}

) : null} - +
{request.action.policy?.behaviour === "hand_off" ? ( @@ -500,7 +521,14 @@ function AnswerDialog({ * Allow for this conversation and Always allow here in the menu; for a hand-off, Don't do it and I * did it myself. The action's own row and the row of a task waiting on it both answer with these. */ -function RequestAnswers({ request }: { request: WaitingRequest }) { +function RequestAnswers({ + request, + more = null, +}: { + request: WaitingRequest; + /** Menu items of the row it answers on (a task's Mark done and Open), put in this one's menu. */ + more?: ReactNode; +}) { const decision = useMutation(decideApprovalMutationOptions(queryClient)); const words = approvalWords(request.action); const handOff = request.action.policy?.behaviour === "hand_off"; @@ -561,7 +589,7 @@ function RequestAnswers({ request }: { request: WaitingRequest }) { > - + decide("allow_conversation")} @@ -574,11 +602,22 @@ function RequestAnswers({ request }: { request: WaitingRequest }) { > Always allow here + {more ? ( + <> + + {more} + + ) : null} + ) : more ? ( + {more} ) : null} )} + {handOff && more ? ( + {more} + ) : null} ); } @@ -602,14 +641,20 @@ function requestReason(request: WaitingRequest): ReactNode { */ function RequestBoardRow({ request }: { request: WaitingRequest }) { const words = approvalWords(request.action); - const action = words.action.charAt(0).toUpperCase() + words.action.slice(1); + /* + * A share is titled as its card is, who it goes to included: "Hand this to Ledger Bot". Split as + * an action and its place, it read "Hand this to" over "Ledger Bot". + */ + const share = shareOf(request.action) !== null; + const said = share ? approvalPhrase(request.action) : words.action; + const action = said.charAt(0).toUpperCase() + said.slice(1); return ( } - detail={words.place} + detail={share ? null : words.place} icon={} meta={[requestReason(request)]} - more={} + more={} open title={action} waiting @@ -622,7 +667,14 @@ function RequestBoardRow({ request }: { request: WaitingRequest }) { * Answer, for a question a task waits on, from the board: the dialog with the whole question and * the box to answer in, so the person answers without opening the thread. And Dismiss beside it. */ -function QuestionAnswers({ question }: { question: WaitingQuestion }) { +function QuestionAnswers({ + question, + more = null, +}: { + question: WaitingQuestion; + /** Menu items of the row it answers on (a task's Mark done and Open), in a menu after Dismiss. */ + more?: ReactNode; +}) { const [answering, setAnswering] = useState(false); const dismiss = useMutation( dismissPersonQuestionMutationOptions(queryClient), @@ -646,6 +698,9 @@ function QuestionAnswers({ question }: { question: WaitingQuestion }) { > + {more ? ( + {more} + ) : null} ReactNode; meta: ReactNode[]; more?: ReactNode; }; @@ -684,9 +740,9 @@ export function useHeldAnswers(): (task: { : undefined; if (request) return { - actions: , + actions: (more) => , meta: [requestReason(request)], - more: , + more: , }; const question = waiting.questions.find( (asked) => @@ -695,7 +751,7 @@ export function useHeldAnswers(): (task: { ); if (question) return { - actions: , + actions: (more) => , meta: question.why ? [{question.why}] : [], }; return undefined; diff --git a/app/src/components/bot-agents/agent-callback-token.tsx b/app/src/components/bot-agents/agent-callback-token.tsx new file mode 100644 index 0000000000..30d51bb876 --- /dev/null +++ b/app/src/components/bot-agents/agent-callback-token.tsx @@ -0,0 +1,84 @@ +import { useMutation } from "@tanstack/react-query"; +import { useState } from "react"; +import { Button } from "@/components/ui/button"; +import { + issueBotAgentCallbackTokenMutationOptions, + revokeBotAgentCallbackTokenMutationOptions, +} from "@/lib/bot-agents/mutations"; +import type { AgentRecord } from "@/lib/bot-agents/queries"; +import { queryClient } from "@/query-client"; + +/** + * The key an agent at its own address presents when it calls a tool back, as the Bot's own key panel + * offers it (components/agents/callback-token-panel.tsx). + * + * Shown once, and said plainly: OpenBot keeps only a hash, so nothing can show it again. A call made + * with it is allowed only for a run of a Bot that may use this agent, as the person that run is for. + */ +export function AgentCallbackToken({ agent }: { agent: AgentRecord }) { + const issue = useMutation( + issueBotAgentCallbackTokenMutationOptions(queryClient), + ); + const revoke = useMutation( + revokeBotAgentCallbackTokenMutationOptions(queryClient), + ); + /** Held in state, not in a query cache: it must not survive a refetch or a navigation. */ + const [token, setToken] = useState(null); + const error = issue.error ?? revoke.error; + + return ( +
+

+ {agent.hasCallbackToken + ? "This agent has a key, so it can use the apps of the Bots that hand it work. If you make a new key, the old one stops working right away." + : "This agent has no key yet. It can answer but can't use apps. Generate a key and add it to your agent's configuration."} +

+ {token ? ( +
+

+ Copy this key now. You won't see it again. +

+ + {token} + +

+ If you lose it, make a new one. +

+ +
+ ) : ( +
+ + {agent.hasCallbackToken ? ( + + ) : null} +
+ )} + {error ? ( +

+ {error.message} +

+ ) : null} +
+ ); +} diff --git a/app/src/components/bot-agents/agent-list.tsx b/app/src/components/bot-agents/agent-list.tsx new file mode 100644 index 0000000000..21790e6dbb --- /dev/null +++ b/app/src/components/bot-agents/agent-list.tsx @@ -0,0 +1,174 @@ +import { IconDots, IconPlus, IconSitemap } from "@tabler/icons-react"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import { Fragment, useState } from "react"; +import { + PageEmpty, + PageRows, + PageSection, +} from "@/components/layout/page-shell"; +import { MetaTag } from "@/components/needs-you/board-row"; +import { Button } from "@/components/ui/button"; +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuGroup, + DropdownMenuItem, + DropdownMenuTrigger, +} from "@/components/ui/dropdown-menu"; +import { + Item, + ItemActions, + ItemContent, + ItemDescription, + ItemFooter, + ItemTitle, +} from "@/components/ui/item"; +import { Separator } from "@/components/ui/separator"; +import { deleteBotAgentMutationOptions } from "@/lib/bot-agents/mutations"; +import { + type AgentRecord, + botAgentListQueryOptions, + whereItRuns, +} from "@/lib/bot-agents/queries"; +import { queryClient } from "@/query-client"; +import { AgentCallbackToken } from "./agent-callback-token"; +import { AgentMark } from "./agent-mark"; + +/** "Used by 2 Bots", or "Not used by any Bot yet". */ +export function usedBy(count: number): string { + if (count === 0) return "Not used by any Bot yet"; + return `Used by ${count} ${count === 1 ? "Bot" : "Bots"}`; +} + +/** + * Every agent the person's Bots may hand work to: OpenBot's own, and the ones the organization and + * the person added. Each row says where it runs and how many Bots use it. Changing and deleting are + * in the row's menu, for whoever may manage it; a key for calling tools back is offered on an agent + * at its own address that OpenBot doesn't run. + */ +export function AgentList({ + onAdd, + onEdit, +}: { + onAdd: () => void; + onEdit: (agent: AgentRecord) => void; +}) { + const agents = useQuery(botAgentListQueryOptions()); + const remove = useMutation(deleteBotAgentMutationOptions(queryClient)); + const [refusal, setRefusal] = useState<{ id: string; message: string }>(); + const [keyFor, setKeyFor] = useState(); + + if (agents.isPending) return null; + if (agents.data === undefined) + return ( +

+ Couldn't load your agents. Try again in a moment. +

+ ); + if (agents.data.length === 0) + return ( + + + + Add agent + + } + icon={IconSitemap} + title="No agents yet" + > + Add an agent your Bots can hand work to. + + + ); + + return ( + + + {agents.data.map((agent, index) => ( + + {index > 0 ? : null} + + + + {agent.name} + {agent.description} + + {agent.canManage ? ( + + + + + + } + /> + + + onEdit(agent)}> + Change + + {agent.kind === "address" && !agent.builtIn ? ( + + setKeyFor( + keyFor === agent.id ? undefined : agent.id, + ) + } + > + Key for tools + + ) : null} + {/* Immediate, with no undo, so it names the agent it deletes. */} + { + setRefusal(undefined); + remove.mutate(agent.id, { + onError: (error) => + setRefusal({ + id: agent.id, + message: error.message, + }), + }); + }} + variant="destructive" + > + Delete {agent.name} + + + + + + ) : null} + + {whereItRuns(agent)} + {usedBy(agent.botCount)} + {agent.visibility === "private" ? ( + Private + ) : null} + + {refusal?.id === agent.id ? ( + +

+ {refusal.message} +

+
+ ) : null} + {keyFor === agent.id ? ( + + + + ) : null} +
+
+ ))} +
+
+ ); +} diff --git a/app/src/components/bot-agents/agent-mark.tsx b/app/src/components/bot-agents/agent-mark.tsx new file mode 100644 index 0000000000..3bdeb670a3 --- /dev/null +++ b/app/src/components/bot-agents/agent-mark.tsx @@ -0,0 +1,41 @@ +import { WEB_HARNESSES } from "@openbot/shared/harnesses"; +import { IconSitemap } from "@tabler/icons-react"; +import { HarnessMark } from "@/components/agents/harness-mark"; +import { OpenBotLogo } from "@/components/edition/openbot-logo"; +import { ItemMedia } from "@/components/ui/item"; +import type { AgentRecord } from "@/lib/bot-agents/queries"; + +/** The framework's mark id for the name the server gives (`framework`), or null for none. */ +export function markIdFor(framework: string | undefined): string | null { + if (!framework) return null; + return ( + WEB_HARNESSES.find((harness) => harness.name === framework)?.mark ?? null + ); +} + +/** + * An agent's leading picture: OpenBot's own mark for an agent that runs inside OpenBot, the + * framework's mark for one that names a framework with a mark, and the Agents glyph otherwise. + * Never a monogram drawn to fill the gap (`shared/marks/README.md`). + * + * In a row's media tile by default; `bare` draws the picture alone, for a tile of the caller's own. + */ +export function AgentMark({ + agent, + bare = false, +}: { + agent: Pick; + bare?: boolean; +}) { + const mark = agent.kind === "openbot" ? null : markIdFor(agent.framework); + const picture = + agent.kind === "openbot" ? ( + + ) : mark ? ( + + ) : ( + + ); + if (bare) return picture; + return {picture}; +} diff --git a/app/src/components/bot-agents/agent-sheet.tsx b/app/src/components/bot-agents/agent-sheet.tsx new file mode 100644 index 0000000000..5fec00413d --- /dev/null +++ b/app/src/components/bot-agents/agent-sheet.tsx @@ -0,0 +1,685 @@ +import { WEB_HARNESSES } from "@openbot/shared/harnesses"; +import { IconLock, IconPlus, IconUsers, IconX } from "@tabler/icons-react"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import { useState } from "react"; +import { CustomAgentCta } from "@/components/agents/custom-agent-cta"; +import { + EndpointStep, + OPTION_CLASSES, + type Runtime, + RuntimeStep, +} from "@/components/agents/new-bot-sheet"; +import { Button } from "@/components/ui/button"; +import { + Field, + FieldDescription, + FieldGroup, + FieldLabel, + FieldLegend, + FieldSet, +} from "@/components/ui/field"; +import { Input } from "@/components/ui/input"; +import { + Select, + SelectContent, + SelectGroup, + SelectItem, + SelectTrigger, + SelectValue, +} from "@/components/ui/select"; +import { + Sheet, + SheetClose, + SheetContent, + SheetFooter, + SheetTitle, +} from "@/components/ui/sheet"; +import { Textarea } from "@/components/ui/textarea"; +import { agentFormSchema } from "@/lib/agents/form"; +import { testAgentConnection } from "@/lib/agents/queries"; +import { + BotAgentHarness, + type BotAgentSkill, + type BotAgentVisibility, +} from "@/lib/api/generated/model"; +import { currentUserQueryOptions } from "@/lib/auth/queries"; +import { isOrganizationAdmin } from "@/lib/auth/roles"; +import { + createBotAgentMutationOptions, + updateBotAgentMutationOptions, +} from "@/lib/bot-agents/mutations"; +import type { AgentRecord } from "@/lib/bot-agents/queries"; +import { deploymentCapabilitiesQueryOptions } from "@/lib/deployment/queries"; +import { modelCatalogueQueryOptions } from "@/lib/models/queries"; +import { queryClient } from "@/query-client"; + +/** The value the model picker gives "the organization's default", which the API sends as null. */ +const DEFAULT_MODEL = "__default__"; + +const STEPS = ["about", "runtime", "endpoint"] as const; +type Step = (typeof STEPS)[number]; + +/** A skill as the form holds it, with a key of its own so a row keeps its place while typed in. */ +type SkillDraft = { key: number; name: string; description: string }; + +/** + * Where an agent is added, or changed: a sheet from the right, so the list stays in view behind it. + * + * Adding takes the New Bot sheet's steps. What it is called and what it is good at come first, and + * by default it runs inside OpenBot. "Connect an agent you run" goes through the same framework list + * and address step New Bot has, and the address is tried with a real run before anything is saved. + */ +export function AgentSheet({ + open, + editing, + onClose, +}: { + open: boolean; + /** The agent being changed, or undefined to add one. */ + editing?: AgentRecord; + onClose: () => void; +}) { + return ( + { + if (!next) onClose(); + }} + open={open} + > + + {/* Inside the popup, so it unmounts on close and a reopened sheet starts afresh. */} + + + + ); +} + +function harnessFor(runtime: Runtime | null): BotAgentHarness | undefined { + if (runtime?.kind !== "managed") return undefined; + const known: readonly string[] = Object.values(BotAgentHarness); + return runtime.harness !== "" && known.includes(runtime.harness) + ? (runtime.harness as BotAgentHarness) + : undefined; +} + +function AgentFlow({ + editing, + onDone, +}: { + editing?: AgentRecord; + onDone: () => void; +}) { + const personal = + useQuery(deploymentCapabilitiesQueryOptions()).data?.edition === "personal"; + const me = useQuery(currentUserQueryOptions()).data; + const admin = isOrganizationAdmin(me?.role); + const create = useMutation(createBotAgentMutationOptions(queryClient)); + const update = useMutation(updateBotAgentMutationOptions(queryClient)); + const saving = create.isPending || update.isPending; + const failure = create.error ?? update.error; + + const [step, setStep] = useState("about"); + const [name, setName] = useState(editing?.name ?? ""); + const [description, setDescription] = useState(editing?.description ?? ""); + const [visibility, setVisibility] = useState( + editing?.visibility ?? "private", + ); + const [model, setModel] = useState(editing?.model ?? DEFAULT_MODEL); + const [skills, setSkills] = useState(() => + (editing?.skills ?? []).map((skill, index) => ({ + key: index, + name: skill.name, + description: skill.description, + })), + ); + const [runtime, setRuntime] = useState( + editing?.kind === "address" + ? { kind: "managed", harness: "byo-url" } + : { kind: "builtin" }, + ); + const [endpoint, setEndpoint] = useState(editing?.endpoint ?? ""); + const [key, setKey] = useState(""); + const [tried, setTried] = useState(false); + const [checking, setChecking] = useState(false); + const [unreachable, setUnreachable] = useState(); + const [missing, setMissing] = useState(); + + const kind = runtime?.kind === "managed" ? "address" : "openbot"; + const catalogue = useQuery({ + ...modelCatalogueQueryOptions(), + enabled: kind === "openbot", + }); + const busy = checking || saving; + const endpointIssue = + endpoint.trim() === "" + ? "Enter your agent's address." + : agentFormSchema.shape.endpoint.safeParse(endpoint).error?.issues[0] + ?.message; + const addressChanged = + kind === "address" && + (endpoint.trim() !== (editing?.endpoint ?? "") || key.trim() !== ""); + + const go = (to: Step) => { + setTried(false); + setUnreachable(undefined); + create.reset(); + update.reset(); + setStep(to); + }; + + /** What the person typed, checked: a name, and what the agent is good at. */ + const aboutIssue = (): string | undefined => { + if (!name.trim()) return "Give the agent a name."; + if (!description.trim()) + return "Say what this agent is good at, so your Bots know what to send it."; + if (skills.some((skill) => !skill.name.trim() || !skill.description.trim())) + return "Give each thing it's good at a name and a description, or remove it."; + return undefined; + }; + + const shownSkills = (): BotAgentSkill[] => + skills.map((skill) => ({ + name: skill.name.trim(), + description: skill.description.trim(), + })); + + /** Dial the address from the server before it is saved, as New Bot does. */ + const reachable = async (): Promise => { + if (endpointIssue) { + setTried(true); + document.getElementById("new-bot-endpoint")?.focus(); + return false; + } + setUnreachable(undefined); + setChecking(true); + const verdict = await testAgentConnection(endpoint.trim(), key).finally( + () => setChecking(false), + ); + if (!verdict.ok) { + setUnreachable(verdict.reason); + document.getElementById("new-bot-endpoint")?.focus(); + return false; + } + return true; + }; + + const save = async () => { + const issue = aboutIssue(); + if (issue) { + setMissing(issue); + if (step !== "about") go("about"); + return; + } + setMissing(undefined); + if (kind === "address" && (!editing || addressChanged)) { + if (!(await reachable())) return; + } + const auth = key.trim() + ? { auth: { header: "Authorization", value: key.trim() } } + : {}; + const chosenModel = model === DEFAULT_MODEL ? null : model; + // One person, and the Bot they start with is the install's own: an agent here is for every Bot. + const shown: BotAgentVisibility = personal ? "public" : visibility; + if (editing) { + await update.mutateAsync({ + botAgentId: editing.id, + input: { + name: name.trim(), + description: description.trim(), + visibility: shown, + skills: shownSkills(), + ...(kind === "openbot" ? { model: chosenModel } : {}), + ...(kind === "address" && addressChanged + ? { endpoint: endpoint.trim(), ...auth } + : {}), + }, + }); + } else { + const harness = harnessFor(runtime); + await create.mutateAsync({ + name: name.trim(), + description: description.trim(), + visibility: shown, + kind, + skills: shownSkills(), + ...(kind === "openbot" + ? { model: chosenModel } + : { + endpoint: endpoint.trim(), + ...auth, + ...(harness ? { harness } : {}), + }), + }); + } + onDone(); + }; + + const submit = () => { + if (busy) return; + if (step === "about" && kind === "address" && !editing) { + const issue = aboutIssue(); + if (issue) { + setMissing(issue); + return; + } + setMissing(undefined); + go("endpoint"); + return; + } + // The failure is shown from the mutation's own state; nothing more to do with it here. + void save().catch(() => undefined); + }; + + const title = editing ? `Change ${editing.name}` : "Add agent"; + const primary = checking + ? "Checking…" + : saving + ? "Saving…" + : editing + ? "Save" + : step === "about" && kind === "address" + ? "Continue" + : "Add agent"; + + return ( +
{ + event.preventDefault(); + submit(); + }} + > +
+ + {title} + +
+ {step === "about" ? ( + ({ + id: option.id, + label: option.label, + })) + : null + } + description={description} + kind={kind} + model={model} + name={name} + onDescription={setDescription} + onModel={setModel} + onName={setName} + onSkills={setSkills} + onVisibility={setVisibility} + personal={personal} + runtime={runtime} + skills={skills} + visibility={visibility} + /> + ) : step === "runtime" ? ( + { + setRuntime(chosen); + go("about"); + }} + /> + ) : ( + { + setEndpoint(value); + setTried(false); + setUnreachable(undefined); + }} + onKey={(value) => { + setKey(value); + setUnreachable(undefined); + }} + secret={key} + /> + )} + {editing && kind === "address" && step === "about" ? ( +
+ { + setEndpoint(value); + setTried(false); + setUnreachable(undefined); + }} + onKey={(value) => { + setKey(value); + setUnreachable(undefined); + }} + secret={key} + /> + {editing.hasAuth ? ( +

+ A key is set. Leave the key empty to keep it. +

+ ) : null} +
+ ) : null} +
+ + {step === "about" && !editing ? ( +
+ {kind === "openbot" ? ( + go("runtime")} /> + ) : ( + + )} +
+ ) : null} + + {missing ? ( +

+ {missing} +

+ ) : failure ? ( +

+ {failure.message} +

+ ) : null} +
+ + + {step === "about" ? ( + } + > + Cancel + + ) : ( + + )} + {step !== "runtime" ? ( + + ) : null} + +
+ ); +} + +/** The two ways an agent can be seen. Public is an admin's to give. */ +const VISIBILITY_OPTIONS: Array<{ + value: BotAgentVisibility; + title: string; + description: string; + icon: typeof IconLock; +}> = [ + { + value: "private", + title: "Private", + description: "Only your Bots can use it.", + icon: IconLock, + }, + { + value: "public", + title: "Everyone", + description: "Every Bot in your organization can use it.", + icon: IconUsers, + }, +]; + +function AboutFields({ + name, + description, + visibility, + model, + skills, + kind, + runtime, + catalogue, + admin, + personal, + onName, + onDescription, + onVisibility, + onModel, + onSkills, +}: { + name: string; + description: string; + visibility: BotAgentVisibility; + model: string; + skills: SkillDraft[]; + kind: "openbot" | "address"; + runtime: Runtime | null; + /** The models it can run on, or null for an agent whose model is its own. */ + catalogue: Array<{ id: string; label: string }> | null; + admin: boolean; + personal: boolean; + onName: (value: string) => void; + onDescription: (value: string) => void; + onVisibility: (value: BotAgentVisibility) => void; + onModel: (value: string) => void; + onSkills: (value: SkillDraft[]) => void; +}) { + const framework = + runtime?.kind === "managed" + ? WEB_HARNESSES.find((harness) => harness.id === runtime.harness) + : undefined; + return ( + +

+ {kind === "openbot" + ? "Runs in OpenBot, with the apps of whichever Bot hands it work." + : framework && framework.id !== "byo-url" + ? `An agent you run on ${framework.name}. OpenBot connects to it.` + : "An agent you run. OpenBot connects to it."} +

+ + Name + onName(event.target.value)} + placeholder="Researcher" + value={name} + /> + + + What it's good at +