Gestionar agentes

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:

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.

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

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);

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);

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)

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

La respuesta es un objeto agent con un id estable como agt_.... Consulte la Referencia de la 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.

# Listar agentes
mka1 agents list --order desc

# Recuperar un solo agente por 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(
    security={"bearer_auth": "Bearer YOUR_API_KEY"},
)

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

Consulte la Referencia de la API para listar agentes y la Referencia de la 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 Respuestas a través de mkllm-gateway.

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 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(
    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)

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

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

# 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

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(
    security={"bearer_auth": "Bearer YOUR_API_KEY"},
    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>'

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 la API para listar ejecuciones de un agente y la Referencia de la 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 suavemente 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 la API para actualizar un agente y la Referencia de la API para eliminar un agente para los detalles del endpoint. Revise la Guía de la API de Respuestas si desea comparar la ejecución de agentes guardados con solicitudes de respuesta puntuales.

​Crear un agente

​Listar y recuperar agentes

​Ejecutar un agente guardado

​Inspeccionar el historial de ejecuciones

​Actualizar o eliminar un agente

Crear un agente

Listar y recuperar agentes

Ejecutar un agente guardado

Inspeccionar el historial de ejecuciones

Actualizar o eliminar un agente