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

# Manage 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/execute-a-saved-agent)

## 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>
  ```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>'
  ```

  ```ts fetch theme={null}
  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);
  ```

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

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

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

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  agent = sdk.agents.create_agent(
      security={"bearer_auth": "Bearer YOUR_API_KEY"},
      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)
  ```

  ```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>

The response is 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>
  ```bash CLI theme={null}
  # List agents
  mka1 agents list --order desc

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

  ```ts fetch theme={null}
  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));
  ```

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

  ```python Python SDK theme={null}
  agents = sdk.agents.list_agents(
      security={"bearer_auth": "Bearer YOUR_API_KEY"},
  )

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

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

<CodeGroup>
  ```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"
    }
  }'
  ```

  ```ts fetch theme={null}
  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);
  ```

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

  ```python Python SDK theme={null}
  run = sdk.agent_runs.create_agent_run(
      security={"bearer_auth": "Bearer YOUR_API_KEY"},
      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)
  ```

  ```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/execute-a-saved-agent) 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>
  ```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
  ```

  ```ts fetch theme={null}
  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);
  ```

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

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

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

  ```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 soft-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>'
```

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.

Review the [Responses API guide](/docs/generate-a-response) if you want to compare saved-agent execution with one-off response requests.