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

# Gestionar agentes

> Cree definiciones de agentes reutilizables, ejecútelas más tarde e inspeccione el historial de ejecuciones persistidas.

Utilice la API de Agentes cuando desee objetos de agente de primera clase y reutilizables en lugar de construir una solicitud de Respuestas desde cero cada vez.
Un agente almacena la elección del modelo, instrucciones y configuración de herramientas.
Cada ejecución persiste la entrada más el resultado de la API de Respuestas aguas arriba.

Referencia de la API:

* [Endpoints de colección e ítem de agentes](/es/api-reference/agents/list-agents)
* [Endpoints de ejecución de agente](/es/api-reference/agent-runs/execute-a-saved-agent)

## Crear un agente

Cree un agente una vez y luego reutilice su comportamiento guardado en múltiples ejecuciones.
El siguiente ejemplo almacena instrucciones y una herramienta `web_search` para que ejecuciones posteriores puedan llamar a herramientas externas cuando sea necesario.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 agents create --body '{
    "name": "release-research-agent",
    "description": "Looks up current release information before answering.",
    "model": "meetkai:functionary-es-mini",
    "instructions": "Use web search when the question depends on current external information.",
    "tools": [
      {
        "type": "web_search",
        "search_context_size": "medium"
      }
    ],
    "tool_choice": "meetkai:functionary-es-mini",
    "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: "meetkai:functionary-es-mini",
      instructions: "Use web search when the question depends on current external information.",
      tools: [
        {
          type: "web_search",
          search_context_size: "medium"
        }
      ],
      tool_choice: "meetkai:functionary-es-mini",
      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 = "meetkai:functionary-es-mini",
          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="meetkai:functionary-es-mini",
      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": "meetkai:functionary-es-mini",
      "instructions": "Use web search when the question depends on current external information.",
      "tools": [
        {
          "type": "web_search",
          "search_context_size": "medium"
        }
      ],
      "tool_choice": "meetkai:functionary-es-mini",
      "parallel_tool_calls": true,
      "metadata": {
        "team": "docs"
      }
    }'
  ```
</CodeGroup>

La respuesta es un objeto `agent` con un `id` estable como `agt_...`.
Consulte la [Referencia de la API para crear un agente](/es/api-reference/agents/create-an-agent) para ver el esquema completo.

## Listar y recuperar agentes

Utilice el endpoint de colección para listar los agentes guardados para el llamador actual.
Utilice el endpoint de ítem cuando ya conozca el ID del agente.

<CodeGroup>
  ```bash CLI theme={null}
  # Listar agentes
  mka1 agents list --order desc

  # Recuperar un solo agente por 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>

Consulte la [Referencia de la API para listar agentes](/es/api-reference/agents/list-agents) y la [Referencia de la API para recuperar un agente](/es/api-reference/agents/retrieve-an-agent) para ver las formas completas de respuesta.

## Ejecutar un agente guardado

Ejecute el agente enviando solo la entrada por ejecución y metadatos opcionales.
El servicio combina esto con la configuración guardada del agente y reenvía la solicitud a la API de Respuestas a través de `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 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>

La respuesta de la ejecución incluye:

* el ID de la ejecución persistida
* el estado de la ejecución
* `gateway_response_id` de la llamada a Respuestas aguas arriba
* `gateway_response`, que contiene la salida almacenada del asistente y cualquier actividad de herramientas

Si la ejecución utilizó `web_search`, el `gateway_response` persistido incluirá las entradas correspondientes de llamadas a herramientas.
Consulte la [Referencia de la API para ejecutar un agente guardado](/es/api-reference/agent-runs/execute-a-saved-agent) para ver el esquema completo de solicitud y respuesta de ejecución.

## Inspeccionar el historial de ejecuciones

Utilice la colección de ejecuciones para listar ejecuciones previas de un agente.
Utilice el endpoint de detalle de ejecución para recuperar un resultado almacenado nuevamente más tarde.

<CodeGroup>
  ```bash CLI theme={null}
  # Listar ejecuciones para un agente
  mka1 agent-runs list --agent-id agt_123

  # Recuperar una sola ejecución
  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>

Para recuperar una ejecución directamente:

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

Consulte la [Referencia de la API para listar ejecuciones de un agente](/es/api-reference/agent-runs/list-runs-for-an-agent) y la [Referencia de la API para recuperar una ejecución de agente](/es/api-reference/agent-runs/retrieve-an-agent-run) para ver el esquema completo del historial de ejecuciones.

## Actualizar o eliminar un agente

Utilice `POST /api/v1/agents/{agent_id}` para actualizar la configuración almacenada.
Utilice `DELETE /api/v1/agents/{agent_id}` para eliminar suavemente el agente cuando ya no deba aceptar nuevas ejecuciones.

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

Consulte la [Referencia de la API para actualizar un agente](/es/api-reference/agents/update-an-agent) y la [Referencia de la API para eliminar un agente](/es/api-reference/agents/delete-an-agent) para los detalles del endpoint.

Revise la [Guía de la API de Respuestas](/es/docs/generate-a-response) si desea comparar la ejecución de agentes guardados con solicitudes de respuesta puntuales.