# Create agent

`POST /v1/projects/{project}/agents`, operation `agents.CreateAgent`

Creates an agent with its full configuration.

Its model must be available in the project.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `project` | path | Yes | `string` | The project's ID. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `NewAgentConfig` | Yes | How the agent works, as it is: nothing fills what it leaves out. Its model and environment are required, and it has no tools where it names none. |
| `config.environment` | `NewAgentEnvironmentConfig` | Yes | The environment the agent runs commands in. People choose it; the agent never does. |
| `config.instructions` | `string` | No | Instructions the agent follows, on top of kosem's own, at most 32,000 characters. |
| `config.maxModelCalls` | `integer (int32)` | No | The most times the agent calls its model after someone last wrote to it, before it pauses until someone writes again: from 10 to 2,000, and at most what the agents.maxModelCalls policy allows. Unset, 1,000, or the policy's max where lower. |
| `config.model` | `string` | Yes | The alias of a model shared with the agent's project, such as claude. |
| `config.reasoningEffort` | `string` | No | How much the model reasons before it answers; empty for the model's default. Values: "", `NONE`, `MINIMAL`, `LOW`, `MEDIUM`, `HIGH`, `XHIGH`, `MAX`. |
| `config.tools` | `string[]` | No | The tools the agent may use, by ID, such as web_search, of those the agents.allowedTools policy allows; none where empty. GET /v1/tools lists them. |
| `grants` | `NewAgentGrant[]` | No | Access profiles and secrets of the project that the agent can use, with optional narrowing scopes and expiry times. |
| `secretGrants` | `string[]` | No | The secrets of the project that the agent can use, as projects/{project_id}/secrets/{secret_id}. Each takes the caller's own access to the secret, as GrantAgentSecrets does. |
| `title` | `string` | No | A title for people, at most 200 characters. Unset, the agent writes one after its first answer. |
| `visibility` | `string` | No | Who sees the agent; PROJECT unless set. Values: `PROJECT`, `PRIVATE`. |

## Responses

### 201

Created

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activityTime` | `string (date-time)` | Yes | When the agent was last active, as people see it, which lists order agents by: when it was created, someone wrote to it or answered it, or it stopped, as it finished its turn, asked a question, was interrupted or failed. Unlike updateTime, the steps of a turn leave it. |
| `awaitingCalls` | `string[]` | Yes | The tool calls that the agent waits for answers to, in AWAITING_INPUT. |
| `config` | `AgentConfig` | Yes | How the agent works. Set when the agent is created, then changed only by configChange events. |
| `config.environment` | `AgentEnvironmentConfig` | No | The environment the agent runs commands in, with exec, which its first command makes and each starts as it needs to; absent when nothing is set. |
| `config.instructions` | `string` | Yes | Instructions the agent follows, on top of kosem's own. |
| `config.maxModelCalls` | `integer (int32)` | Yes | The most times the agent calls its model after someone last wrote to it, before it pauses as CALL_LIMIT_REACHED until someone writes again. The agents.maxModelCalls policy lowers it where it allows fewer, for running agents too. |
| `config.model` | `string` | Yes | The alias of a model shared with the agent's project, such as claude. |
| `config.reasoningEffort` | `string` | Yes | How much the model reasons before it answers; empty for the model's default. A level the model lacks becomes the nearest it has. Values: "", `NONE`, `MINIMAL`, `LOW`, `MEDIUM`, `HIGH`, `XHIGH`, `MAX`. |
| `config.tools` | `string[]` | Yes | The tools the agent may use, by ID, such as web_search. A tool that the agents.allowedTools policy no longer allows is not offered, with a warning in the transcript. |
| `createTime` | `string (date-time)` | Yes | When the agent was created. |
| `creator` | `string` | Yes | Who created the agent, such as user:usr_…. |
| `environment` | `AgentEnvironment` | No | The agent's environment, which its first command makes; absent while it has none. |
| `environment.diskGib` | `integer (int32)` | Yes | Its disk's size, in GiB. |
| `environment.environment` | `string` | Yes | The environment's resource name, by which people who may stop or delete a project's environments do so through the environments API. |
| `environment.memoryMib` | `integer (int32)` | Yes | Its memory, in MiB. |
| `environment.state` | `string` | Yes | Where it is in its lifecycle. Values: `PROVISIONING`, `RUNNING`, `STOPPING`, `STOPPED`, `STARTING`, `DELETING`. |
| `environment.stateReason` | `string` | Yes | What it waits for, such as capacity, when it waits. |
| `environment.updateTime` | `string (date-time)` | Yes | When it last changed. |
| `environment.vcpus` | `integer (int32)` | Yes | Its virtual CPUs. |
| `jobs` | `AgentJob[]` | Yes | The background jobs that the agent left running and is told the end of, while its environment runs. As each ends, it starts a turn of an IDLE agent, unless someone interrupted its last turn, so an agent that finished its turn with jobs goes on when they end. |
| `lastSequence` | `integer (int64)` | Yes | The sequence of the transcript's last event. |
| `lastStop` | `AgentStop` | No | Why the agent last stopped; absent until it first does. |
| `lastStop.message` | `string` | Yes | What happened, for people, when it did not simply finish. |
| `lastStop.reason` | `string` | Yes | Why it stopped: END_TURN, it finished its turn; INTERRUPTED, someone interrupted it; LIMIT_REACHED, a limit of billing, a spend limit or a quota stopped it, and writing to it goes on only once the limit allows; CALL_LIMIT_REACHED, it called its model as many times as it can since someone last wrote to it, and writing to it lets it go on; ERROR, something failed, such as the model being unavailable. Values: `END_TURN`, `INTERRUPTED`, `LIMIT_REACHED`, `CALL_LIMIT_REACHED`, `ERROR`. |
| `name` | `string` | Yes | Resource name, projects/{project_id}/agents/{agent_id}. |
| `state` | `string` | Yes | What the agent is doing: IDLE with nothing to do, as lastStop says, until a message starts it again; QUEUED with work it starts on shortly; RUNNING; or AWAITING_INPUT, waiting for answers to the tool calls in awaitingCalls, such as a question it asked. Values: `IDLE`, `QUEUED`, `RUNNING`, `AWAITING_INPUT`. |
| `title` | `string` | Yes | A title for people, at most 200 characters. Empty until the agent writes one after its first answer, unless someone set it. |
| `unread` | `boolean` | Yes | Whether the agent stopped since the caller last read it: it finished its turn, failed or reached a limit, and is IDLE. Only for agents the caller follows, as people follow those they created, sent to or marked unread; always false for service accounts. MarkAgentRead marks it read. |
| `updateTime` | `string (date-time)` | Yes | When the agent last changed, or had an event. |
| `usage` | `AgentUsage` | Yes | What the agent used, all told. |
| `usage.webSearches` | `integer (int64)` | Yes | The web searches the search service answered. |
| `visibility` | `string` | Yes | Who sees the agent: PROJECT, everyone who may see the project's agents, by their roles on it; PRIVATE, its owner, those it is shared with through its IAM policy, and those who hold agents.agents.accessPrivate on the project. Values: `PROJECT`, `PRIVATE`. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.