Saltar para o conteúdo principal
Use a API de Agentes quando quiser objetos de agente reutilizáveis e tratados como recursos de primeira classe, em vez de montar uma requisição da API de Responses do zero toda vez. Um agente armazena a escolha do modelo, as instruções e a configuração de ferramentas. Cada execução salva a entrada e também o resultado retornado pela chamada upstream à API de Responses. Referência da API:

​
Criar um agente

Crie um agente uma vez e depois 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. 
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-urdu-mini-pak",
    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);
A resposta é um objeto agent com um id estável, como agt_.... Consulte a referência da API de criação de agente para ver o esquema completo.

​
Listar e recuperar agentes

Use o endpoint de coleção para listar os agentes salvos para o chamador atual. Use o endpoint do item quando já souber o ID do 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 a referência da API de listagem de agentes e a referência da API de recuperação de um agente para ver os formatos completos de resposta.

​
Executar um agente salvo

Execute o agente enviando apenas a entrada específica da execução e metadados opcionais. O serviço combina isso com a configuração salva do agente e encaminha a requisição para a API de Responses por meio do 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);
A resposta da execução inclui:
  • o ID persistido da execução
  • o status da execução
  • o gateway_response_id da chamada upstream para a API de Responses
  • o gateway_response, que contém a saída armazenada do assistente e qualquer atividade de ferramenta
Se a execução tiver usado web_search, o gateway_response persistido incluirá as entradas correspondentes de chamada de ferramenta. Consulte a referência da API de execução de um agente salvo para ver o esquema completo da solicitação e da 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 novamente, mais tarde, um resultado armazenado. 
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 diretamente uma execução: 
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 de listagem de execuções de um agente e a referência da API de recuperação de 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 fazer uma exclusão lógica do 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 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 a referência da API de atualização de agente e a referência da API de exclusão de agente para ver os detalhes do endpoint. Revise o guia da API de Responses se quiser comparar a execução de agentes salvos com requisições pontuais à API de Responses.