> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciar agentes

> Crie definições de agentes reutilizáveis, execute-as posteriormente e inspecione o histórico de execuções persistidas.

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:

* [Coleção de agentes e endpoints de item](/pt/api-reference/agents/list-agents)
* [Endpoints de execução de agente](/pt/api-reference/agent-runs/execute-a-saved-agent)

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

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts fetch theme={null}
  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-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"
      }
    }),
  });

  const agent = await response.json();
  console.log(agent.id);
  ```

  ```csharp C# SDK theme={null}
  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-pt",
          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);
  ```

  ```python Python SDK theme={null}
  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-pt",
      instructions="Use web search when the question depends on current external information.",
      metadata={"team": "docs"},
  )

  print(agent.id)
  ```

  ```bash bash theme={null}
  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-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"
      }
    }'
  ```
</CodeGroup>

A resposta é um objeto `agent` com um `id` estável como `agt_...`.
Veja a [referência da API de criação de agente](/pt/api-reference/agents/create-an-agent) 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.

<CodeGroup>
  ```bash CLI theme={null}
  # Listar agentes
  mka1 agents list --order desc

  # Recuperar um agente pelo id
  mka1 agents get --agent-id agt_123
  ```

  ```ts fetch theme={null}
  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));
  ```

  ```csharp C# SDK theme={null}
  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);
  ```

  ```python Python SDK theme={null}
  agents = sdk.agents.list_agents(
      security={"bearer_auth": "Bearer YOUR_API_KEY"},
  )

  print([agent.id for agent in agents.data])
  ```

  ```bash bash theme={null}
  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>'
  ```
</CodeGroup>

Veja a [referência da API de listar agentes](/pt/api-reference/agents/list-agents) e [referência da API de recuperar um agente](/pt/api-reference/agents/retrieve-an-agent) 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`.

<CodeGroup>
  ```bash CLI theme={null}
  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"
    }
  }'
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```csharp C# SDK theme={null}
  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);
  ```

  ```python Python SDK theme={null}
  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)
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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](/pt/api-reference/agent-runs/execute-a-saved-agent) 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.

<CodeGroup>
  ```bash CLI theme={null}
  # 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
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```csharp C# SDK theme={null}
  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);
  ```

  ```python Python SDK theme={null}
  runs = sdk.agent_runs.list_agent_runs(
      security={"bearer_auth": "Bearer YOUR_API_KEY"},
      agent_id="agt_123",
  )

  print(runs.data[0].id)
  ```

  ```bash bash theme={null}
  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>'
  ```
</CodeGroup>

Para recuperar uma execução diretamente:

```bash theme={null}
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](/pt/api-reference/agent-runs/list-runs-for-an-agent) e [referência da API de recuperar uma execução de agente](/pt/api-reference/agent-runs/retrieve-an-agent-run) 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.

```bash theme={null}
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."
  }'
```

```bash theme={null}
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](/pt/api-reference/agents/update-an-agent) e [referência da API de excluir agente](/pt/api-reference/agents/delete-an-agent) para detalhes dos endpoints.

Consulte o [guia da API de Respostas](/pt/docs/generate-a-response) se quiser comparar a execução de agentes salvos com requisições de resposta avulsas.