> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and run agents

> Create reusable agent definitions, execute them later, and inspect persisted run history.

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:

* [Agents collection and item endpoints](/api-reference/agents/list-agents)
* [Agent run endpoints](/api-reference/agent-runs/start-a-saved-agent-run)

## 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.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  import { SDK } from '@meetkai/mka1';

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

  const agent = await sdk.agents.createAgent({
    xOnBehalfOf: '<end-user-id>',
    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.',
      tools: [{ type: 'web_search', searchContextSize: 'medium' }],
      toolChoice: 'auto',
      parallelToolCalls: true,
      metadata: { team: 'docs' },
    },
  });
  console.log(agent.id);
  ```

  ```python Python SDK theme={null}
  from meetkai_mka1 import SDK

  sdk = SDK(bearer_auth="Bearer <mka1-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.",
      tools=[{"type": "web_search", "search_context_size": "medium"}],
      tool_choice="auto",
      parallel_tool_calls=True,
      metadata={"team": "docs"},
  )

  print(agent.id)
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

  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.",
          Tools = new List<ToolDefinitionUnion>
          {
              ToolDefinitionUnion.CreateToolDefinition1(new ToolDefinition1
              { SearchContextSize = ToolDefinitionSearchContextSize.Medium }),
          },
          ToolChoice = "auto",
          ParallelToolCalls = true,
          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);
  ```

  ```bash CLI theme={null}
  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>'
  ```

  ```bash Bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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](/api-reference/agents/create-an-agent) 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.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const agents = await sdk.agents.listAgents({ limit: 20, order: 'desc', xOnBehalfOf: '<end-user-id>' });
  console.log(agents.data.map(agent => agent.id));
  ```

  ```python Python SDK theme={null}
  agents = sdk.agents.list_agents()

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

  ```csharp C# SDK theme={null}
  var agents = await sdk.Agents.ListAgentsAsync(
      xOnBehalfOf: "<end-user-id>"
  );

  Console.WriteLine(agents);
  ```

  ```bash CLI theme={null}
  # List agents
  mka1 agents list --order desc

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

  ```bash Bash theme={null}
  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>'
  ```
</CodeGroup>

See the [List agents API reference](/api-reference/agents/list-agents) and [Retrieve an agent API reference](/api-reference/agents/retrieve-an-agent) 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.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const run = await sdk.agentRuns.createAgentRun({
    agentId: 'agt_123',
    xOnBehalfOf: '<end-user-id>',
    createAgentRunRequest: {
      input: "What is Bun's current stable version? Use web search before answering.",
      metadata: { request_source: 'docs' },
    },
  });
  console.log(run.gatewayResponseId, run.status);
  ```

  ```python Python SDK theme={null}
  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)
  ```

  ```csharp C# SDK theme={null}
  var run = await sdk.AgentRuns.CreateAgentRunAsync(
      agentId: "agt_123",
      body: new MeetKai.MKA1.Types.Components.CreateAgentRunRequest()
      {
          Input = CreateAgentRunRequestInputUnion.CreateStr("What is Bun's current stable version? Use web search before answering."),
          Metadata = new Dictionary<string, string> { { "request_source", "docs" } },
      },
      xOnBehalfOf: "<end-user-id>"
  );

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

  ```bash CLI theme={null}
  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"
    }
  }'
  ```

  ```bash Bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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](/api-reference/agent-runs/start-a-saved-agent-run) 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.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const runs = await sdk.agentRuns.listAgentRuns({ agentId: 'agt_123', xOnBehalfOf: '<end-user-id>' });
  console.log(runs.data);
  ```

  ```python Python SDK theme={null}
  runs = sdk.agent_runs.list_agent_runs(
      agent_id="agt_123",
  )

  print(runs.data[0].id)
  ```

  ```csharp C# SDK theme={null}
  var runs = await sdk.AgentRuns.ListAgentRunsAsync(
      agentId: "agt_123",
      xOnBehalfOf: "<end-user-id>"
  );

  Console.WriteLine(runs.AgentRunList);
  ```

  ```bash CLI theme={null}
  # 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
  ```

  ```bash Bash theme={null}
  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>'
  ```
</CodeGroup>

To retrieve one run directly:

```bash theme={null}
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](/api-reference/agent-runs/list-runs-for-an-agent) and [Retrieve an agent run API reference](/api-reference/agent-runs/retrieve-an-agent-run) 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.

```bash theme={null}
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."
  }'
```

```bash theme={null}
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:

```json theme={null}
{
  "object": "agent.deleted",
  "id": "agt_123",
  "deleted": true
}
```

See the [Update an agent API reference](/api-reference/agents/update-an-agent) and [Delete an agent API reference](/api-reference/agents/delete-an-agent) 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](/docs/agent-connectors-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](/docs/cli/commands) does not list version commands, so this section has no CLI tab.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const versions = await sdk.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 sdk.agentVersions.getAgentVersion({
    agentId: 'agt_123',
    version: 1,
    xOnBehalfOf: '<end-user-id>',
  });
  console.log(first.model, first.tools);

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

  ```python Python SDK theme={null}
  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
  ```

  ```csharp C# SDK theme={null}
  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
  ```

  ```bash Bash theme={null}
  # 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>'
  ```
</CodeGroup>

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](/api-reference/agent-versions/list-agent-versions), [Retrieve an agent version](/api-reference/agent-versions/retrieve-an-agent-version), and [Roll back an agent to a version](/api-reference/agent-versions/roll-back-an-agent-to-a-version) API references.

Review the [Responses API guide](/docs/generate-a-response) 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](/docs/agent-connectors-and-schedules).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.