Saltar al contenido principal
Utilice la API de Agentes cuando desee objetos de agente de primera clase y reutilizables, en lugar de construir una solicitud de Responses desde cero cada vez. Un agente almacena la elección del modelo, instrucciones y la configuración de herramientas. Cada ejecución persiste la entrada junto con el resultado de la API de Responses aguas arriba. Referencia de la API:

​
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 las ejecuciones posteriores puedan llamar herramientas externas cuando sea necesario. 
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: "gpt-5",
    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);
La respuesta es un objeto agent con un id estable como agt_.... Consulte la Referencia de API para crear un agente 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. 
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));
Consulte la Referencia de API para listar agentes y la Referencia de API para recuperar un agente 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 Responses a través de mkllm-gateway. 
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);
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 Responses aguas arriba
  • gateway_response, que contiene la salida almacenada del asistente y cualquier actividad de herramienta
Si la ejecución usó web_search, el gateway_response persistido incluirá las entradas correspondientes de llamadas a herramientas. Consulte la Referencia de API para ejecutar un agente guardado 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. 
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);
Para recuperar una ejecución directamente: 
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 API para listar ejecuciones de un agente y la Referencia de API para recuperar una ejecución de agente 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 lógicamente el agente cuando ya no deba aceptar nuevas ejecuciones. 
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>'
Consulte la Referencia de API para actualizar un agente y la Referencia de API para eliminar un agente para los detalles del endpoint. Revise la Guía de la API de Responses si desea comparar la ejecución de agentes guardados con solicitudes de respuesta puntuales.