Set up a first agent

Get Started in the portal sets up one agent and starts its first run. Without it, defining an agent takes an identity, a content store, a policy, uploaded instructions and schemas, a budget, grants and a published version, each on its own page. Tutorial: run a managed agent takes that path with the API, as a free simulation.

Setup runs in an organization’s Test environment, for an owner or admin. The first run is real Test Compute paid from your account’s credits, so the account needs one credit available. A new account’s signup credit covers it.

Choose a starter

Starter	What the agent does	Its first run
General Assistant	Answers a task in text	Introduces itself and lists what it can help with
Summarizer	Returns a short summary and the key points of a text	Summarizes a sample paragraph
Blank Agent	Follows instructions you write	Carries out the first task you write

A blank agent’s instructions can be up to 32 KiB and its first task up to 4,000 characters. Every starter answers through Cortex.

What setup creates

The page lists nine steps and marks each one as it finishes:

1. An agent identity with a service account of its own.
2. A content store for its files, unless the environment already has one.
3. A starter policy, if the environment has no active policy. It allows model calls and tool actions, and holds any tool action that writes for approval by a new team named Approvers, with you as its first member.
4. The agent’s instructions, its input and output schemas, and the first run’s input.
5. A budget of one credit. Funding it reserves one credit of your balance for the agent, with consent to spend it on Test Compute.
6. Grants that let the agent’s runs start and call Cortex.
7. The agent’s first published version.
8. Read access for the agent to that version’s instructions and schemas.
9. The first run.

Select Watch the First Run to follow it. The agent then appears on the Agents page; publish another version to change what it does. The run form offers to give the agent read access to whatever a new version pins.

The grants and the spending consent last thirty days. After that the agent needs new ones to run, and whatever the budget did not spend goes back to your balance. Closing the budget under Budgets & Grants returns it sooner.

On day 24, when 80% of that time has passed, Katara sends you a reminder in the inbox and by email. It links to the agent’s New Run page, which from then on offers Renew: one review sets up another thirty days with a new budget, so the agent keeps running without a gap. The old budget keeps its credit reserved until it ends, unless you close it.

Whoever issued an agent’s grants cannot approve its actions, so an approval under the starter policy needs a teammate. Add one to Approvers before giving the agent a tool that writes. Approving is done by a person signed in to the portal; an API key cannot approve.

When setup stops part way

Each finished step is kept, and you have one setup under way per environment. Get Started shows it wherever you open the page, in another tab or on another device, and Continue Setup resumes after the last finished step without creating a second agent. To choose a different starter, select Start Over: the setup is discarded and any credit it held goes back to your balance. What it already made, such as the agent, stays.

A new organization’s access can take a few seconds to arrive; the page tries again on its own. If less than one credit is available, add credits in Billing and continue.

Use the API

startSetup / start_setup takes starter and, for a blank agent, instructions and first_task. It needs a person’s signed-in session; API keys cannot start a setup. While you have a setup under way in the environment, starting again with the same request continues it whatever the idempotency key, and a different request answers setup_in_progress. Once it has finished, a new key starts another.

The response lists each step and whether it is done, with the request the setup was started with. A setup is done once its first run is admitted, and then carries agent_id and run_id; follow the run with run events. A step that cannot finish returns its error instead: reauthentication_required asks you to sign in again, product_access_unavailable means access has not arrived yet, and budget_unavailable means the account cannot reserve the credit.

getCurrentSetup / get_current_setup returns the setup you have under way, so another client can continue it, and discardSetup / discard_setup gives it up and returns its credit. getSetup / get_setup reads any setup you started. Only the person who started a setup can read or discard it.