Pick an agent's model, voice and skills

An agent on the Claude API or the OpenAI API uses your base's own account at Anthropic or OpenAI. Base Captain sends each of its calls to an AI model directly to that service, under your API key: each step of its runs, its reading of a file, of a web page or of a page's picture, and the titles of its chats. None of that goes to the AI of Base Captain. The base's admins and AI managers set it up.

1. Get an API key from your account at Anthropic or at OpenAI.
2. An admin saves the key as a secret: click Settings, then Secrets, and Add secret. Give it a name, such as ANTHROPIC_KEY, paste the key, and under Which service is this key for? pick Anthropic, or OpenAI for a key of OpenAI (Store the keys of other services). The key is then sent only to api.anthropic.com or to api.openai.com.
3. On the agent's form, click the card Claude API or OpenAI API, and under API key pick the secret. The list shows only the secrets saved for that service. When there is none, the form says so, with a link to Secrets.
4. Pick its Model from the models that your account at that service offers, which Base Captain reads with your key. With no model, the agent uses a default model of that service. When the list cannot be read, you type the model's name, and the reason shows under the field, such as "Anthropic refused the API key in the secret ANTHROPIC_KEY." Pick its Reasoning as for any agent: default, low, medium or high.

Who pays for the agent's AI

Your account at Anthropic or OpenAI pays for the agent's AI, at the prices of that service. It costs Base Captain nothing, so it counts in no AI allowance, on every plan, the Free plan included. The agent goes on when the base reaches its fair-use limit: in a chat, by itself, in a workflow, in a try and in a trial. A web search or a page read through Base Captain's AnyAPI account still uses the plan's AI (Search the web). The limits of a run, such as a step's time limit, stay the same.

Where your data goes

What the agent reads goes to Anthropic or OpenAI under your base's own agreement with that service, as it goes to an MCP server that you add. The switch that keeps the base's data from AI stops these agents too (Keep your records away from AI). In a chat, such an agent is not kept to the base's work, as an agent on Base Captain is (Chat with an agent).

What stops the agent

Four problems stop an agent on the Claude API or the OpenAI API. Each one shows on the agent's page, with a link to Secrets (Find what stops an agent from running), and a run that meets one fails with the same sentence:

• The secret does not exist: "The secret ANTHROPIC_KEY does not exist. Add it in Settings › Secrets, for Anthropic."
• The secret is saved for another service: "The secret STRIPE_OTHER is saved for Stripe. Save the API key for Anthropic."
• The service refuses the key: "Anthropic refused the API key in the secret ANTHROPIC_KEY."
• The account at the service has no credit: "The Anthropic account of the secret ANTHROPIC_KEY has no credit." Add credit at the service. The line goes when a later run goes through, or when an admin replaces the secret.

None of them stops you from saving the agent: correct the secret, and the agent runs.

Move the agent to another service

On a saved agent, click another of the cards Base Captain, Claude API and OpenAI API, then save. Its Model and Reasoning go empty, since each service has its own models: pick them again. An agent cannot move to or from Your machine, whose settings are different, so that card is locked on an agent in Base Captain, and the other three on a machine agent.

With an API token or the assistant

Under the API token of someone who builds the base (Use your base from a calendar or a script), the agent's runs_on is "claude_api" or "openai_api", and its secret is the name of the secret, never its value, such as {"runs_on": "claude_api", "secret": "ANTHROPIC_KEY", "model": "claude-haiku-5-5"}. A move empties the model and the reasoning unless you send new ones. GET /api/builder/models?runs_on=claude_api&secret=ANTHROPIC_KEY lists the models, and when it cannot, models_error says why. Through Base Captain's MCP server and in the assistant, list_models lists the models and propose_change sets the agent, with its put_agent: ask, for example, "Make an agent Writer on the Claude API, with the key in ANTHROPIC_KEY." The key's value is never shown: not on a page, in a run's record, in an answer or in an error.

A Claude Code agent on a machine can take its model from a secret of your base, saved for Anthropic, in place of the Claude Code login on the machine. The key stays in your base: it never goes to the machine. The base's builders set it up.

1. An admin saves the key as a secret: click Settings, then Secrets, and Add secret. Give it a name, such as ANTHROPIC_KEY, paste the key, and under Which service is this key for? pick Anthropic (Store the keys of other services).
2. Open the page of an agent that runs on your machine with Claude Code (Put an agent on a machine). Under Where its model comes from, click A secret of this base. The other choice, This machine's login, is the one every machine agent has until you change it.
3. Pick the secret. The list shows only the secrets saved for Anthropic. Then pick the Model, or type its name, such as opus. Click Save agent.

How it works

Claude Code runs on your machine as before. Its requests for the model go to Base Captain with a token that works for that one run, and Base Captain adds your key and sends them on to api.anthropic.com. The token allows model requests and nothing else, a limited number of them, and ends when the run ends. The run's record shows each call to the model with its tokens (See everything a run did).

Who pays for the agent's AI

Your account at Anthropic pays, at Anthropic's prices. The agent uses none of the base's AI allowance, so it goes on when the base reaches its fair-use limit.

When the key has no credit or Anthropic refuses it

• The agent's page shows what stops it, as for an agent on the Claude API (Find what stops an agent from running): a secret that does not exist, a secret saved for another service, and a key that Anthropic refuses, such as "Anthropic refused the API key in the secret ANTHROPIC_KEY." Correct the secret and the agent runs.
• If the account at Anthropic has no credit, the run of a workflow step waits and does not fail. The step does not move on, no attempt of the step is used, and the item says "Waits: the Anthropic account of the secret ANTHROPIC_KEY has no credit. Save the secret again to run it." The base shows a notice about it once. Add credit at Anthropic, then save the secret again in Settings, Secrets: the waiting step runs at once.
• In a chat, the run ends with the sentence of the problem, and nothing waits.

Limits and details

• Only Claude Code does this. Codex, pi and opencode cannot take their model from a secret: Base Captain refuses to save such an agent, and a run on a coding tool that you added under a name refuses with "… is not Claude Code: only Claude Code takes its model from a secret."
• The agent's permission, directory and the rest of its machine settings work as for any machine agent.

With an API token or the assistant

Under the API token of someone who builds the base (Use your base from a calendar or a script), set the agent's secret to the name of the secret, never its value, such as {"runs_on": "machine", "tool": "claude", "secret": "ANTHROPIC_KEY", "model": "opus"}. In the assistant and through Base Captain's MCP server, put_agent sets it: ask, for example, "Let Coder use the key in ANTHROPIC_KEY." The key's value is never shown.

A trial runs an agent's latest workflow step runs again on another model, so you can try a cheaper model before you move the agent to it. Its latest step runs, at most 20, run again on the model and reasoning level you pick, each from what its run was told. Only the model changes, so you see run by run whether it ends the step the same way. A trial is for the admins and the AI managers, on the page of an agent in Base Captain.

1. In Settings, Agents, open an agent in Base Captain that works a workflow step, such as the example shop's Reviewer, and click Try another model.
2. Pick the Model, the Reasoning level, and how many of its latest step runs to try, then click Start trial.
3. Read the result, which fills in on the agent's page while the trial runs, one run at a time. For each run: its item, the outcome the agent named and the one the trial named (or "Asked a person", "Stopped without finishing", "Failed"), with a mark where they differ. Below, the share of runs that agree.
4. Happy with it? Click Switch to this model: the agent is saved with the trial's model and reasoning level, a change of the base like any other, with its version in Activity, Versions.

A trial changes nothing. When the agent writes, in the trial, an item or a comment, it is told the change is done, but no data changes. It tells nobody: no notification, no mail, nothing in the Inbox or an item's history. It reaches no MCP server. What it reads, it reads from the base as it is now, and it follows the agent's instructions and skills as they are now, so a trial after you changed them tries the agent as it is today.

Limits and details:

• Only step runs are tried, since a step's outcome is what can be compared.
• A machine agent has no trial.
• A trial's runs use the plan's AI, as any run of the agent. If agents have reached this month's fair-use limit, the trial stops there and says so.
• For an agent on the Claude API or the OpenAI API, the trial offers the models of its service, runs them with its API key and uses none of the plan's AI.
• A trial's runs are listed in Agent runs, marked Trial, and never count in the agent's share of runs that went through.
• The result stays until the agent's next trial.

Or ask the assistant, such as "Would Reviewer work on a cheaper model?" It reads the models, proposes the trial on a card, and starts it only when you click Start trial. Later it reads the result and tells you the share that agree; switching the model is then a card like any change. It never starts a trial on its own.

The same is there under the API token of an admin or an AI manager (Use your base from a calendar or a script): the models and the latest result at GET /api/builder/agents/<id>/trial, and a new trial at POST /api/builder/agents/<id>/trial, with the model, the reasoning level and how many runs. Through Base Captain's MCP server, the tools read_trial and start_trial do the same; start_trial starts at once there, since your AI client asks you first. Only the admins and the AI managers see any of it.

An agent's Picture sets how it looks. The base's admins and AI managers set it on the General tab of the agent's page in Settings, Agents, after the instructions. It may stay empty. Click Save when you are done.

Click the emoji box and pick one emoji, such as 🦊. The icons at the top go to each group of emoji. Search all emoji finds an emoji by its name or by a word for it, such as fox. The emoji you pick most show first, under Frequently used. No emoji removes the emoji. Then pick a color: the agent shows as that emoji on a circle of that color. To use an image instead, click Upload image and choose a PNG, JPEG or WebP file of at most 256 KB. The image shows in place of the emoji. Remove image brings the emoji back. An agent with no emoji and no image shows its initials, on the color that you pick. On a new agent, the image is kept when you create the agent.

An agent has no voice setting. To say how it writes, such as its tone, the length of its replies or its use of emoji, write it in the agent's instructions.

The Greeting is on the agent's Chat tab. It is up to 300 characters that show as the agent's first message in a new chat with it. Your browser shows the greeting: the agent does not write it, the chat does not keep it, and it uses no AI.

The picture shows wherever the agent writes: in the assistant's panel, in chat, in an item's comments and in its history, with the mark Agent beside the name (See an agent's changes in an item's history). In the example shop, Intake has an emoji picture and a greeting, and Reviewer has an image.

Limits and details:

• The assistant has a picture too. Its page opens from the first row of Agents. It has only a name and a picture, and no voice (Give the assistant a name and a picture).

You can also ask the assistant, for example "Give Intake a fox on teal": it shows the change on a card first. It can also use an image that is already in the base, in an item's files or in Files, such as "Use the photo on this bill as Intake's picture". To use an image of your own, upload it on the agent's page. With an API token, the agent's picture is part of the agent, and the image goes to PUT /api/builder/pictures/<agent>.

Skills and the agent's Instructions tell agents how your base works: a skill is how a job is done, written once for every agent that needs it. Agents keep no notes of their own and cannot be asked to remember something: what every run of an agent needs goes in its Instructions or in a skill.

• Skills. A skill is how a job is done in your base, such as how you take returns. In Settings, click Skills, then New skill: a Name, When it applies in one line, and How it is done. Click Save skill. An agent is told each skill's name and when it applies, and reads the rest only when it needs it. The example shop's Order priorities tells Order check how to set a priority.
• Every agent. With the skill's Every agent switch on, the skill reaches every agent of the base, and you tick nothing on the agents. If you turn it off, only the agents that pick the skill read it: tick it under Skills on each agent's page, where the skills that reach every agent show as read by every agent. A run is told the agent's own skills first, in their order, then the skills that reach every agent. A change reaches the agents' next runs at once.
• About this base. In Settings, General, a few lines about your business that every agent is told first, before its own instructions. Users see its first sentence in the tour (Take the tour of a base).
• The base's builders and AI managers write the skills, and no other role. Under such a user's API token (Use your base from a calendar or a script), a skill is a change of the base, as any other, with put_skill and delete_skill and its "all": true for every agent. Ask the assistant, such as "Add a skill for every agent about how we take returns": it shows the skill on a card, and saves it when you click Apply. An AI client connected to Base Captain's MCP server does the same with propose_change.