Agents
7 calls. Every request needs the Authorization header: see the overview.
agents.list
Section titled “agents.list”GET /agentsEvery 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.
Response: Agent[] (200)
curl -X GET "https://api.maitento.com/agents" \ -H "Authorization: $MAITENTO_AUTH"const agents = await mt.agents.list();mt.agents.list()agents.delete
Section titled “agents.delete”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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | uuid | yes |
Response: no body (204)
curl -X DELETE "https://api.maitento.com/agents/by-id/<id>" \ -H "Authorization: $MAITENTO_AUTH"await mt.agents.delete("7c9e6679-7425-40de-944b-e07fc1f90ae7");mt.agents.delete("2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b")agents.get
Section titled “agents.get”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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | uuid | yes |
Response: Agent (200)
curl -X GET "https://api.maitento.com/agents/by-id/<id>" \ -H "Authorization: $MAITENTO_AUTH"const agent = await mt.agents.get("7c9e6679-7425-40de-944b-e07fc1f90ae7");mt.agents.get("2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b")agents.update
Section titled “agents.update”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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | uuid | yes |
Request body: AgentUpdateRequest
| 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[] | The tools the agent may call in every interaction it takes part in. | |
routedSubAgents | VersionReference[] | 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 (200)
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":"..."}'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" });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
Section titled “agents.list”GET /namespaces/{namespaceName}/agentsEvery 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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
namespaceName | string | yes |
Response: Agent[] (200)
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/agents" \ -H "Authorization: $MAITENTO_AUTH"const agents = await mt.agents.list({ namespace: "support" });mt.agents.list(namespace="demo")agents.create
Section titled “agents.create”POST /namespaces/{namespaceName}/agentsCreates 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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
namespaceName | string | yes |
Request body: AgentCreateRequest
| 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[] | The tools the agent may call in every interaction it takes part in. | |
routedSubAgents | VersionReference[] | 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 (200)
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/agents" \ -H "Authorization: $MAITENTO_AUTH" \ -H "Content-Type: application/json" \ -d '{"name":"...","aiModelId":"...","systemPrompt":"...","summaryForOtherAgents":"..."}'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" });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
Section titled “agents.getByName”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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
namespaceName | string | yes | |
name | string | yes |
Response: Agent (200)
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/agents/by-name/<name>" \ -H "Authorization: $MAITENTO_AUTH"const agent = await mt.agents.getByName("greeter", { namespace: "support" });mt.agents.get_by_name("greeter", namespace="demo")