Pular para o conteúdo principal
Use a API de Agentes quando quiser objetos de agentes de primeira classe e reutilizáveis, em vez de construir uma requisição de Respostas do zero toda vez. Um agente armazena a escolha do modelo, instruções e configuração de ferramentas. Cada execução persiste a entrada mais o resultado da API de Respostas upstream. 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. 
mka1 agents create --body '{
  "name": "release-research-agent",
  "description": "Looks up current release information before answering.",
  "model": "meetkai:functionary-pt",
  "instructions": "Use web search when the question depends on current external information.",
  "tools": [
    {
      "type": "web_search",
      "search_context_size": "medium"
    }
  ],
  "tool_choice": "meetkai:functionary-pt",
  "parallel_tool_calls": true,
  "metadata": {
    "team": "docs"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'
A resposta é um objeto agent com um id estável como agt_.... Veja a referência da API de criação de agente para o esquema completo.

​
Listar e recuperar agentes

Use o endpoint de coleção para listar agentes salvos para o usuário atual. Use o endpoint de item quando você já souber o ID do agente. 
# Listar agentes
mka1 agents list --order desc

# Recuperar um agente pelo id
mka1 agents get --agent-id agt_123
Veja a referência da API de listar agentes e referência da API de recuperar um agente para os formatos de resposta completos.

​
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 requisição para a API de Respostas através do 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"
  }
}'
A resposta da execução inclui:
  • o ID da execução persistida
  • o status da execução
  • gateway_response_id da chamada de Respostas 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 correspondentes de chamada de ferramenta. Veja a referência da API de executar um agente salvo para o esquema completo de requisição e resposta de execução.

​
Inspecionar 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 execução específica
mka1 agent-runs get --agent-id agt_123 --run-id run_123
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>'
Veja a referência da API de listar execuções de um agente e referência da API de recuperar uma execução de agente para 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 logicamente 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 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>'
Veja a referência da API de atualizar agente e referência da API de excluir agente para detalhes dos endpoints. Consulte o guia da API de Respostas se quiser comparar a execução de agentes salvos com requisições de resposta avulsas.