Manage agents

Use the Agents API when you want first-class, reusable agent objects instead of building a Responses request from scratch every time. An agent stores model choice, instructions, and tool configuration. Each run persists the input plus the upstream Responses API result. API Reference:

Create an agent

Create an agent once, then reuse its saved behavior across multiple runs. The example below stores instructions and a web_search tool so later runs can call external tools when needed.

mka1 agents create --body '{
  "name": "release-research-agent",
  "description": "Looks up current release information before answering.",
  "model": "auto",
  "instructions": "Use web search when the question depends on current external information.",
  "tools": [
    {
      "type": "web_search",
      "search_context_size": "medium"
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "metadata": {
    "team": "docs"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const response = await fetch("https://apigw.mka1.com/api/v1/agents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "release-research-agent",
    description: "Looks up current release information before answering.",
    model: "auto",
    instructions: "Use web search when the question depends on current external information.",
    tools: [
      {
        type: "web_search",
        search_context_size: "medium"
      }
    ],
    tool_choice: "auto",
    parallel_tool_calls: true,
    metadata: {
      team: "docs"
    }
  }),
});

const agent = await response.json();
console.log(agent.id);

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var agent = await sdk.Agents.CreateAgentAsync(
    body: new MeetKai.MKA1.Types.Components.CreateAgentRequest()
    {
        Name = "release-research-agent",
        Description = "Looks up current release information before answering.",
        Model = "auto",
        Instructions = "Use web search when the question depends on current external information.",
        Metadata = new Dictionary<string, string> { { "team", "docs" } },
    },
    xOnBehalfOf: "<end-user-id>" // optional — attribute the request to one of your end users
);

Console.WriteLine(agent.Agent!.Id);

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

agent = sdk.agents.create_agent(
    name="release-research-agent",
    description="Looks up current release information before answering.",
    model="auto",
    instructions="Use web search when the question depends on current external information.",
    metadata={"team": "docs"},
)

print(agent.id)

curl https://apigw.mka1.com/api/v1/agents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "release-research-agent",
    "description": "Looks up current release information before answering.",
    "model": "auto",
    "instructions": "Use web search when the question depends on current external information.",
    "tools": [
      {
        "type": "web_search",
        "search_context_size": "medium"
      }
    ],
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "metadata": {
      "team": "docs"
    }
  }'

On success, the API returns 201 Created with an agent object with a stable id such as agt_.... See the Create an agent API reference for the full schema.

List and retrieve agents

Use the collection endpoint to list saved agents for the current caller. Use the item endpoint when you already know the agent ID.

# List agents
mka1 agents list --order desc

# Retrieve a single agent by id
mka1 agents get --agent-id agt_123

const listResponse = await fetch("https://apigw.mka1.com/api/v1/agents?limit=20&order=desc", {
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const agents = await listResponse.json();
console.log(agents.data.map((agent) => agent.id));

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var agents = await sdk.Agents.ListAgentsAsync(
    xOnBehalfOf: "<end-user-id>"
);

Console.WriteLine(agents);

agents = sdk.agents.list_agents()

print([agent.id for agent in agents.data])

curl 'https://apigw.mka1.com/api/v1/agents?limit=20&order=desc' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

See the List agents API reference and Retrieve an agent API reference for the complete response shapes.

Execute a saved agent

Run the agent by sending only the per-run input and optional metadata. The service combines this with the saved agent configuration and forwards the request into the Responses API through mkllm-gateway. Runs start asynchronously: the create call returns a queued run record. Use run retrieval to poll status, or stream progress via the run events endpoint.

mka1 agent-runs create --agent-id agt_123 --body '{
  "input": [
    {
      "type": "text",
      "text": "What is Bun'"'"'s current stable version? Use web search before answering."
    }
  ],
  "metadata": {
    "request_source": "docs"
  }
}'

const runResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    input: [
      {
        type: "text",
        text: "What is Bun's current stable version? Use web search before answering.",
      },
    ],
    metadata: {
      request_source: "docs"
    }
  }),
});

const run = await runResponse.json();
console.log(run.gateway_response_id);
console.log(run.status);

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var run = await sdk.AgentRuns.CreateAgentRunAsync(
    agentId: "agt_123",
    body: new MeetKai.MKA1.Types.Components.CreateAgentRunRequest()
    {
        Input = CreateAgentRunRequestInputUnion.CreateStr("What is 2 + 2?"),
        Metadata = new Dictionary<string, string> { { "request_source", "docs" } },
    },
    xOnBehalfOf: "<end-user-id>"
);

Console.WriteLine(run.AgentRun!.GatewayResponseId);
Console.WriteLine(run.AgentRun!.Status);

run = sdk.agent_runs.create_agent_run(
    agent_id="agt_123",
    input="What is Bun's current stable version? Use web search before answering.",
    metadata={"request_source": "docs"},
)

print(run.gateway_response_id)
print(run.status)

curl https://apigw.mka1.com/api/v1/agents/agt_123/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "input": [
      {
        "type": "text",
        "text": "What is Bun'"'"'s current stable version? Use web search before answering."
      }
    ],
    "metadata": {
      "request_source": "docs"
    }
  }'

The run response includes:

the persisted run ID
the run status
gateway_response_id from the upstream Responses call
gateway_response, which contains the stored assistant output and any tool activity

If the run used web_search, the persisted gateway_response will include the corresponding tool call entries. See the Execute a saved agent API reference for the full run request and response schema.

Inspect run history

Use the runs collection to list prior executions for one agent. Use the run detail endpoint to retrieve one stored result again later.

# List runs for an agent
mka1 agent-runs list --agent-id agt_123

# Retrieve a single run
mka1 agent-runs get --agent-id agt_123 --run-id run_123

const runsResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const runs = await runsResponse.json();
console.log(runs.data[0]?.id);

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var runs = await sdk.AgentRuns.ListAgentRunsAsync(
    agentId: "agt_123",
    xOnBehalfOf: "<end-user-id>"
);

Console.WriteLine(runs.AgentRunList);

runs = sdk.agent_runs.list_agent_runs(
    agent_id="agt_123",
)

print(runs.data[0].id)

curl https://apigw.mka1.com/api/v1/agents/agt_123/runs \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

To retrieve one run directly:

curl https://apigw.mka1.com/api/v1/agents/agt_123/runs/run_123 \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

See the List runs for an agent API reference and Retrieve an agent run API reference for the complete run-history schema.

Update or delete an agent

Use POST /api/v1/agents/{agent_id} to update stored configuration. Use DELETE /api/v1/agents/{agent_id} to delete the agent when it should no longer accept new runs.

curl https://apigw.mka1.com/api/v1/agents/agt_123 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "instructions": "Use web search for current information. Reply in 3 bullets max."
  }'

curl https://apigw.mka1.com/api/v1/agents/agt_123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

On success, delete returns 200 OK with a deletion result object:

{
  "object": "agent.deleted",
  "id": "agt_123",
  "deleted": true
}

See the Update an agent API reference and Delete an agent API reference for the endpoint details. An agent with connectors cannot be deleted: the call returns 409 until they are gone. Schedules do not block deletion, but they are only reachable through the agent, and deleting it does not delete them, so delete them first. See Connect agents to chat apps and schedules.

Versions and rollback

Every create, update, and rollback appends a version, an immutable copy of the agent’s configuration: name, description, model, instructions, tools, tool_choice, parallel_tool_calls, max_tool_calls, text, reasoning, and metadata. Creation writes version 1, and the agent object’s version is the number of the current one. Each run records agent_version, the version it executed against. A continuation such as an MCP approval keeps using that version, so the agent can change underneath it without changing the run. Rolling back to version N copies N’s configuration into the agent as a new version. Version N itself is untouched, and the new version carries restored_from_version: N, so history never loses an entry. The mka1 CLI reference does not list version commands, so this section has no CLI tab.

import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

const versions = await mka1.agentVersions.listAgentVersions({
  agentId: 'agt_123',
  order: 'asc',
  xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
});
for (const v of versions.data) {
  console.log(v.version, v.isCurrent, v.restoredFromVersion, v.instructions);
}

const first = await mka1.agentVersions.getAgentVersion({
  agentId: 'agt_123',
  version: 1,
  xOnBehalfOf: '<end-user-id>',
});
console.log(first.model, first.tools);

const agent = await mka1.agentVersions.rollbackAgentVersion({
  agentId: 'agt_123',
  version: 1,
  xOnBehalfOf: '<end-user-id>',
});
console.log(agent.version); // the new current version, not 1

const versionsResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/versions?order=asc", {
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const versions = await versionsResponse.json();
console.log(versions.data.map((v) => [v.version, v.is_current, v.restored_from_version]));

const versionResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/versions/1", {
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const first = await versionResponse.json();
console.log(first.model, first.tools);

const rollbackResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/versions/1/rollback", {
  method: "POST",
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const agent = await rollbackResponse.json();
console.log(agent.version); // the new current version, not 1

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var versions = await sdk.AgentVersions.ListAgentVersionsAsync(
    agentId: "agt_123",
    order: MeetKai.MKA1.Types.Requests.ListAgentVersionsOrder.Asc,
    xOnBehalfOf: "<end-user-id>" // optional — attribute the request to one of your end users
);
foreach (var v in versions.AgentVersionList!.Data)
{
    Console.WriteLine($"{v.Version} current={v.IsCurrent} restoredFrom={v.RestoredFromVersion}");
}

var first = await sdk.AgentVersions.GetAgentVersionAsync(
    agentId: "agt_123",
    version: 1,
    xOnBehalfOf: "<end-user-id>"
);
Console.WriteLine(first.AgentVersion!.Model);

var rolledBack = await sdk.AgentVersions.RollbackAgentVersionAsync(
    agentId: "agt_123",
    version: 1,
    xOnBehalfOf: "<end-user-id>"
);
Console.WriteLine(rolledBack.Agent!.Version); // the new current version, not 1

versions = sdk.agent_versions.list_agent_versions(
    agent_id="agt_123",
    order="asc",
    x_on_behalf_of="<end-user-id>",  # optional — attribute the request to one of your end users
)
for v in versions.data:
    print(v.version, v.is_current, v.restored_from_version, v.instructions)

first = sdk.agent_versions.get_agent_version(
    agent_id="agt_123",
    version=1,
    x_on_behalf_of="<end-user-id>",
)
print(first.model, first.tools)

agent = sdk.agent_versions.rollback_agent_version(
    agent_id="agt_123",
    version=1,
    x_on_behalf_of="<end-user-id>",
)
print(agent.version)  # the new current version, not 1

# List the history, oldest first
curl 'https://apigw.mka1.com/api/v1/agents/agt_123/versions?order=asc' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

# Read one version
curl https://apigw.mka1.com/api/v1/agents/agt_123/versions/1 \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

# Roll back: the agent gets a new version with version 1's configuration
curl https://apigw.mka1.com/api/v1/agents/agt_123/versions/1/rollback \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

A version object holds the configuration fields above plus:

Field	Description
`id`	`agtver_...`
`version`	1 for creation, then one higher per update or rollback.
`is_current`	`true` on the version the agent runs today.
`restored_from_version`	The version a rollback copied from, or `null` for a create or update.
`created_at`	When the version was written.

The list is paginated with limit and order (desc by default, so the newest version comes first). Asking for a version number that does not exist returns 404. Rollback needs write:agents and returns the agent object, whose version is the new number. Like update and delete, rollback requires the same X-On-Behalf-Of the agent was created with: a caller sending the header gets 404 on an agent created without it. See the List agent versions, Retrieve an agent version, and Roll back an agent to a version API references. Review the Responses API guide if you want to compare saved-agent execution with one-off response requests. To run an agent from a chat app or on a timer, see Connect agents to chat apps and schedules.

Getting started

Responses

Features

Compute

CLI

Recipes

Benchmarks

Infrastructure

Manage agents

Create an agent

List and retrieve agents

Execute a saved agent

Inspect run history

Update or delete an agent

Versions and rollback

​Create an agent

​List and retrieve agents

​Execute a saved agent

​Inspect run history

​Update or delete an agent

​Versions and rollback

Create an agent

List and retrieve agents

Execute a saved agent

Inspect run history

Update or delete an agent

Versions and rollback