# Set up a first agent

> Create a working agent in the Test environment and watch its first run.

Section: Start. Web page: https://docs.katara.com/start/first-agent/

**Get Started** in the portal sets up one agent and starts its first run. Without it, [defining an agent](https://docs.katara.com/products/runs.txt) 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](https://docs.katara.com/products/tutorial-managed-agent.txt) 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 |
| --- | --- | --- |
| Answer from your documents | Answers from a knowledge collection and quotes the passages it used | Answers a question about three sample documents for a made-up shop |
| An agent that waits for you | Asks your approval before every model call | Waits in **Locus → Approvals** until you approve, then writes a short welcome note |
| Write your own | Follows instructions you write | Carries out the first task you write |

The approval starter puts a policy in force for the whole Test environment that asks for approval before every model call, for every agent there, and lets the person who started a run approve it, so one person can try it alone. The page says so before it starts; when the run has finished, **Turn Approvals Back Off** reviews and activates the policy you had before. Approving needs a person signed in to the portal.

The documents starter's question can be changed before it runs, up to 4,000 bytes; its answer comes only from the sample documents, and each claim names the document and sentence it rests on. Your own agent's instructions can be up to 32 KiB and its first task up to 4,000 bytes. Every starter answers through [Cortex](https://docs.katara.com/concepts/cortex.txt).

Before it runs, the page says what the agent is, what the run will do and what it costs. While it runs, it shows how far it has got: planning, the safety check every model call passes, the document search, and the model's answer. The answer comes first when it finishes, with the run's charge; every file the run wrote is under **Details**.

## What setup creates

The page lists each step and marks it 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. For the documents starter, the sample documents, approved, in a collection of their own that the agent's version lists. Its first run indexes and searches them.
6. A budget of one credit. Funding it reserves one credit of your balance for the agent, with consent to spend it on Test Compute.
7. Grants that let the agent's runs start and call Cortex.
8. The agent's first published version.
9. Read access for the agent to that version's instructions and schemas.
10. The first run.

## Run it from your code

When the run finishes, **Use it from your code** shows the same run as TypeScript, Python and curl, with your organization, environment and the agent's grants, budget and input filled in; only the API key is yours to add. A program can start that run again and print its answer. A new task is new content, and content is approved by a person before a run reads it, so **Try Another Task** opens the agent's **New Run** page, which writes and approves the input for you. [Tutorial: run a managed agent](https://docs.katara.com/products/tutorial-managed-agent.txt) shows the whole path from code.

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.

Under the starter policy, whoever issued an agent's grants cannot approve its actions, so an approval 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; if that person has an authenticator, the sign-in must have used it. An API key cannot approve. A request nobody approves within an hour is denied.

## 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`: `documents`, `approval` or `blank`. A blank agent also takes `instructions` and `first_task`; the documents and approval starters may take `first_task`, the question or the task. A finished approval setup carries `restore_policy`, the policy it replaced; review and activate it to stop asking for approval. Setups started with the earlier `assistant` and `summarizer` starters can still be continued. 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](https://docs.katara.com/products/run-events.txt). 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.