# Agents

7 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `agents.list`

```http
GET /agents
```

Every definition of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fagents).

**Response:** [`Agent`](https://docs.maitento.com/reference/types/agent.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/agents" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const agents = await mt.agents.list();
```
```python title="Python"
mt.agents.list()
```

## `agents.delete`

```http
DELETE /agents/by-id/{id}
```

Deletes the definition (refused with a 400 while something still uses it or a run of it is going).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fagents%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/agents/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.agents.delete("7c9e6679-7425-40de-944b-e07fc1f90ae7");
```
```python title="Python"
mt.agents.delete("2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b")
```

## `agents.get`

```http
GET /agents/by-id/{id}
```

The definition with this id. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fagents%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`Agent`](https://docs.maitento.com/reference/types/agent.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/agents/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const agent = await mt.agents.get("7c9e6679-7425-40de-944b-e07fc1f90ae7");
```
```python title="Python"
mt.agents.get("2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b")
```

## `agents.update`

```http
PUT /agents/by-id/{id}
```

Updates an agent: a new version when anything changed.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fagents%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`AgentUpdateRequest`](https://docs.maitento.com/reference/types/agent-update-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The agent's name, unique within its namespace. |
| `aiModelId` | `uuid` | yes | The id of the catalogue model the agent runs on. |
| `systemPrompt` | `string` | yes | The agent's standing instructions (its system prompt): who it is and how it behaves. |
| `summaryForOtherAgents` | `string` | yes | One line that describes the agent to other agents: a router choosing who answers, or a manager choosing who to hand work to, reads it. |
| `externalOperationReferences` | [`AgentExternalOperationReferenceInput`](https://docs.maitento.com/reference/types/agent-external-operation-reference.md#in-a-request)`[]` |  | The tools the agent may call in every interaction it takes part in. |
| `routedSubAgents` | [`VersionReference`](https://docs.maitento.com/reference/types/version-reference.md)`[] \| null` |  | Makes the agent a router: on every turn it is given, its model picks one of these agents (by their summaries, guided by `systemPrompt`) to take the turn instead. The first is the fallback. A router has no tools of its own. |
| `allowSwarm` | `boolean` |  | Whether the agent may start sub-interactions where an interaction it takes part in allows them. |
| `allowWebSearch` | `boolean` |  | Whether the agent is given the built-in web search tool. An omitted value is false. |
| `allowWebFetch` | `boolean` |  | Whether the agent is given the built-in web fetch tools. An omitted value is false. |

**Response:** [`Agent`](https://docs.maitento.com/reference/types/agent.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/agents/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","aiModelId":"...","systemPrompt":"...","summaryForOtherAgents":"..."}'
```
```ts title="TypeScript"
const agent = await mt.agents.update("7c9e6679-7425-40de-944b-e07fc1f90ae7", { name: "greeter", aiModelId: "2f0c8b9e-6a4d-4c3b-9e1f-7d5a3c1b9e2f", systemPrompt: "You are warm and brief.", summaryForOtherAgents: "Says hello" });
```
```python title="Python"
mt.agents.update("2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", name="greeter", ai_model_id="64b07f92-2576-4abc-ae9c-d2bb96935ab2", system_prompt="You are a terse assistant.", summary_for_other_agents="A terse assistant")
```

## `agents.list`

```http
GET /namespaces/{namespaceName}/agents
```

Every definition of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fagents).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Response:** [`Agent`](https://docs.maitento.com/reference/types/agent.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/agents" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const agents = await mt.agents.list({ namespace: "support" });
```
```python title="Python"
mt.agents.list(namespace="demo")
```

## `agents.create`

```http
POST /namespaces/{namespaceName}/agents
```

Creates an agent (version 1) in the namespace.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fagents).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Request body:** [`AgentCreateRequest`](https://docs.maitento.com/reference/types/agent-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The agent's name, unique within its namespace. |
| `aiModelId` | `uuid` | yes | The id of the catalogue model the agent runs on. |
| `systemPrompt` | `string` | yes | The agent's standing instructions (its system prompt): who it is and how it behaves. |
| `summaryForOtherAgents` | `string` | yes | One line that describes the agent to other agents: a router choosing who answers, or a manager choosing who to hand work to, reads it. |
| `externalOperationReferences` | [`AgentExternalOperationReferenceInput`](https://docs.maitento.com/reference/types/agent-external-operation-reference.md#in-a-request)`[]` |  | The tools the agent may call in every interaction it takes part in. |
| `routedSubAgents` | [`VersionReference`](https://docs.maitento.com/reference/types/version-reference.md)`[] \| null` |  | Makes the agent a router: on every turn it is given, its model picks one of these agents (by their summaries, guided by `systemPrompt`) to take the turn instead. The first is the fallback. A router has no tools of its own. |
| `allowSwarm` | `boolean` |  | Whether the agent may start sub-interactions where an interaction it takes part in allows them. |
| `allowWebSearch` | `boolean` |  | Whether the agent is given the built-in web search tool. An omitted value is false. |
| `allowWebFetch` | `boolean` |  | Whether the agent is given the built-in web fetch tools. An omitted value is false. |

**Response:** [`Agent`](https://docs.maitento.com/reference/types/agent.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/agents" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","aiModelId":"...","systemPrompt":"...","summaryForOtherAgents":"..."}'
```
```ts title="TypeScript"
const agent = await mt.agents.create({ name: "greeter", aiModelId: "2f0c8b9e-6a4d-4c3b-9e1f-7d5a3c1b9e2f", systemPrompt: "You are warm and brief.", summaryForOtherAgents: "Says hello" }, { namespace: "support" });
```
```python title="Python"
mt.agents.create(name="greeter", ai_model_id="64b07f92-2576-4abc-ae9c-d2bb96935ab2", system_prompt="You are a friendly assistant.", summary_for_other_agents="A friendly assistant", namespace="demo")
```

## `agents.getByName`

```http
GET /namespaces/{namespaceName}/agents/by-name/{name}
```

The definition with this name in the namespace. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fagents%2Fby-name%2F%7Bname%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Response:** [`Agent`](https://docs.maitento.com/reference/types/agent.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/agents/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const agent = await mt.agents.getByName("greeter", { namespace: "support" });
```
```python title="Python"
mt.agents.get_by_name("greeter", namespace="demo")
```