Gerenciar agentes

Use a API de Agentes quando quiser objetos de agente reutilizáveis e de primeira classe, em vez de criar uma solicitação de Responses do zero todas as vezes. Um agente armazena a escolha do modelo, as instruções e a configuração de ferramentas. Cada execução persiste a entrada junto com o resultado da API de Responses upstream. Referência da API:

Criar um agente

Crie um agente uma vez e reutilize seu comportamento salvo em várias execuções. O exemplo abaixo armazena instruções e uma ferramenta web_search para que execuções posteriores possam chamar ferramentas externas quando necessário.

mka1 agents create --body '{
  "name": "release-research-agent",
  "description": "Busca informações atuais sobre versões antes de responder.",
  "model": "meetkai:functionary-pt",
  "instructions": "Use a pesquisa na web quando a pergunta depender de informações externas atuais.",
  "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>'

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: "Busca informações atuais sobre versões antes de responder.",
    model: "meetkai:functionary-pt",
    instructions: "Use a pesquisa na web quando a pergunta depender de informações externas atuais.",
    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);

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 = "Busca informações atuais sobre versões antes de responder.",
        Model = "meetkai:functionary-pt",
        Instructions = "Use a pesquisa na web quando a pergunta depender de informações externas atuais.",
        Metadata = new Dictionary<string, string> { { "team", "docs" } },
    },
    xOnBehalfOf: "<end-user-id>" // opcional — atribua a solicitação a um dos seus usuários finais
);

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

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

agent = sdk.agents.create_agent(
    name="release-research-agent",
    description="Busca informações atuais sobre versões antes de responder.",
    model="meetkai:functionary-pt",
    instructions="Use a pesquisa na web quando a pergunta depender de informações externas atuais.",
    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": "Busca informações atuais sobre versões antes de responder.",
    "model": "meetkai:functionary-pt",
    "instructions": "Use a pesquisa na web quando a pergunta depender de informações externas atuais.",
    "tools": [
      {
        "type": "web_search",
        "search_context_size": "medium"
      }
    ],
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "metadata": {
      "team": "docs"
    }
  }'

Em caso de sucesso, a API retorna 201 Created com um objeto agent que tem um id estável, como agt_.... Consulte a referência da API Criar um agente para ver o esquema completo.

Listar e recuperar agentes

Use o endpoint de coleção para listar os agentes salvos do chamador atual. Use o endpoint de item quando já souber o ID do agente.

# Listar agentes
mka1 agents list --order desc

# Recuperar um único agente pelo 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()

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 a referência da API Listar agentes e a referência da API Recuperar um agente para ver os formatos completos de resposta.

Executar um agente salvo

Execute o agente enviando apenas a entrada por execução e metadados opcionais. O serviço combina isso com a configuração salva do agente e encaminha a solicitação para a API de Responses por meio do mkllm-gateway. As execuções começam de forma assíncrona: a chamada de criação retorna um registro de execução enfileirado. Use a recuperação de execução para consultar o status ou transmita o progresso por streaming pelo endpoint de eventos de execução.

mka1 agent-runs create --agent-id agt_123 --body '{
  "input": [
    {
      "type": "text",
      "text": "Qual é a versão estável atual do Bun? Use a pesquisa na web antes de responder."
    }
  ],
  "metadata": {
    "request_source": "docs"
  }
}'

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: "Qual é a versão estável atual do Bun? Use a pesquisa na web antes de responder.",
      },
    ],
    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("Quanto é 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(
    agent_id="agt_123",
    input="Qual é a versão estável atual do Bun? Use a pesquisa na web antes de responder.",
    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": "Qual é a versão estável atual do Bun? Use a pesquisa na web antes de responder."
      }
    ],
    "metadata": {
      "request_source": "docs"
    }
  }'

A resposta da execução inclui:

o ID da execução persistida
o status da execução
gateway_response_id da chamada de Responses upstream
gateway_response, que contém a saída armazenada do assistente e qualquer atividade de ferramenta

Se a execução usou web_search, o gateway_response persistido incluirá as entradas de chamada de ferramenta correspondentes. Consulte a referência da API Executar um agente salvo para ver o esquema completo de solicitação e resposta de execução.

Inspecionar o histórico de execuções

Use a coleção de execuções para listar execuções anteriores de um agente. Use o endpoint de detalhes da execução para recuperar um resultado armazenado posteriormente.

# Listar execuções de um agente
mka1 agent-runs list --agent-id agt_123

# Recuperar uma única execução
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(
    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 uma execução diretamente:

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 a referência da API Listar execuções de um agente e a referência da API Recuperar uma execução de agente para ver o esquema completo do histórico de execuções.

Atualizar ou excluir um agente

Use POST /api/v1/agents/{agent_id} para atualizar a configuração armazenada. Use DELETE /api/v1/agents/{agent_id} para excluir o agente quando ele não deve mais aceitar novas execuções.

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 a pesquisa na web para informações atuais. Responda em no máximo 3 itens."
  }'

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

Em caso de sucesso, a exclusão retorna 200 OK com um objeto de resultado da exclusão:

{
  "object": "agent.deleted",
  "id": "agt_123",
  "deleted": true
}

Consulte a referência da API Atualizar um agente e a referência da API Excluir um agente para ver os detalhes do endpoint. Consulte o guia da API de Responses se quiser comparar a execução de agentes salvos com solicitações de resposta pontuais.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Gerenciar agentes

Criar um agente

Listar e recuperar agentes

Executar um agente salvo

Inspecionar o histórico de execuções

Atualizar ou excluir um agente

​Criar um agente

​Listar e recuperar agentes

​Executar um agente salvo

​Inspecionar o histórico de execuções

​Atualizar ou excluir um agente

Criar um agente

Listar e recuperar agentes

Executar um agente salvo

Inspecionar o histórico de execuções

Atualizar ou excluir um agente