Invocar um agente

Invoque seu agente

Para invocar um agente, envie uma solicitação POST para o endpoint da API /api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke. A resposta retorna o resultado da execução e o status da execução. A plataforma retorna o ID da sessão no cabeçalho de resposta X-Session-ID.

O exemplo curl a seguir utiliza estes espaços reservados:

• $API_KEY: Sua chave de API do Atlas Agent Engine

• $PROJECT_ID: ID do projeto

• $WORKSPACE_ID: ID do seu workspace

Selecione a guia do idioma de sua preferência para visualizar uma solicitação de invocação de amostra:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"message": "Hello, agent!"},
    timeout=60.0,
)
result = response.json()

A resposta se assemelha à seguinte saída:

{
  "success": true,
  "response": "<agent output>",
  "execution_id": "string",
  "status": "completed"
}

Se a execução for suspensa para revisão humana, a resposta também incluirá os campos suspend_reason e suspend_context. Para saber mais, consulte Suspender, revisar e retomar o ciclo de vida no guiaHuman-in-the-Loop.

Transmita a saída do seu agente

Para transmitir a saída de um agente conforme ela é produzida, envie uma solicitação POST para o endpoint da API /api/v1/projects/{project_id}/workspaces/{workspace_id}/invokeStream. A plataforma retorna a resposta como um fluxo de armações do Server-Sent Events (SSE). O stream mantém a conexão aberta até que a execução seja concluída ou falhe.

Cada armação SSE começa com o prefixo data: e contém um único objeto JSON . O exemplo a seguir mostra o formato de um quadro de streaming:

data: {"chunk_type": "text", "content": "Hello, agent!", "metadata": {}, "execution_id": "string"}

Um framework pode incluir os seguintes campos:

Outros pontos de extremidade

O Atlas Agent Engine também expõe os seguintes pontos de conexão de API para streaming, pesquisa, retomada e interrupção de execuções:

Cada endpoint executions/** requer o parâmetro de query workspace_id. O gateway usa esse valor para rotear a solicitação para o Mecanismo de orquestração do espaço de trabalho proprietário.

Ciclo de vida do status de execução

Uma execução passa pelos status pending, running e, em seguida, completed ou error.

Se a execução for suspensa para revisão humana, ela passará por status adicionais antes de ser concluída. Para saber mais sobre o ciclo de vida de suspensão e retomada, consulte Suspender, revisar e retomar o ciclo de vida no guiaHuman-in-the-Loop.

Se você cancelar uma execução, ela atingirá o status cancelled. Esse status é diferente de completed e error, para que os clientes de API e UI possam distinguir uma execução deliberadamente interrompida de uma que concluiu ou falhou. Para saber mais, consulte Cancelar uma sessão.

Erros completos do pool

O Atlas Agent Engine não dimensiona automaticamente os sistemas do agente . O campo scaling.replicas no arquivo agent.yaml define uma contagem fixa de sandbox, e cada sessão reserva uma sandbox de agente e uma sandbox de ferramenta para sua vida útil. Como resultado, este campo define o número de sessões que um sistema pode atender simultaneamente.

O campo scaling.replicas aceita um valor de 1 a 512 e padroniza para 4 quando você o omite. Quando cada sandbox é reservada, uma nova solicitação de invocação falha com um erro pool full.

O limite de sandbox simultânea 512 se aplica ao Mecanismo de orquestração, que tem como escopo um projeto e pode atender a mais de um agente. Os valores scaling.replicas de todos os agentes em um projeto contam para o mesmo teto. Para executar mais sandboxes do que um projeto permite, distribua seus agentes em vários projetos.

Para evitar que as solicitações de invocação esgotem o pool, reutilize os IDs de sessão nas solicitações. As solicitações que compartilham um ID de sessão reutilizam uma reserva, mas as solicitações que omitem um ID de sessão usam um novo par de sandboxes. Um ID de sessão deve ter 1 a 128 caracteres e pode conter letras, números, sublinhados (_) e hífens (-). Passe o ID da sessão na opção --session do comando agentengine invoke ou no cabeçalho X-Session-ID de uma solicitação de API.

Se suas solicitações de invocação exigirem isolamento por sessão, você não poderá reutilizar um ID de sessão. Para atender a mais sessões ao mesmo tempo, aumente o valor scaling.replicas ou reduza os valores scaling.agent_idle_ttl_seconds e scaling.tool_idle_ttl_seconds para que as sessões ociosas liberem suas sandboxes mais cedo.

Como o Atlas Agent Engine captura valores scaling no tempo de construção, você deve construir e distribuir o agente novamente para que uma alteração entre em vigor. Para saber mais sobre esses campos, consulte Referência do contrato do agente. Para revisar todas as limitações que se aplicam durante a visualização pública, consulte Limitações do mecanismo do agente do MongoDB Atlas .

Como funciona

Em uma solicitação de invocação ou retomada, o API Gateway processa cabeçalhos HTTP com o prefixo X-Mdb-Agent-Engine-Custom- executando as seguintes etapas:

1. O gateway de API extrai o cabeçalho.

2. O gateway remove o prefixo e torna o nome do cabeçalho em minúsculas. Por exemplo, X-Mdb-Agent-Engine-Custom-Authorization torna-se authorization.

3. O gateway encaminha os cabeçalhos para o agente como um dicionário.

Os cabeçalhos são encaminhados na memória por meio do pipeline de execução, nunca são persistidos no banco de dados e descartados pelo pipeline quando a execução é concluída.

Enviar cabeçalhos personalizados

Adicione cabeçalhos prefixados X-Mdb-Agent-Engine-Custom- à sua solicitação de invocação. O API Gateway remove o prefixo antes que o agente o receba.

Os exemplos a seguir usam os mesmos espaços reservados que os exemplos de API de invocação. Eles também usam espaços reservados para os cabeçalhos personalizados que você deseja encaminhar.

Selecione a guia do seu idioma preferido para ver um exemplo de solicitação de invocação com cabeçalhos personalizados:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Mdb-Agent-Engine-Custom-Authorization: my-user-id" \
  -H "X-Mdb-Agent-Engine-Custom-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke",
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Mdb-Agent-Engine-Custom-Authorization": "my-user-id",
        "X-Mdb-Agent-Engine-Custom-Tenant-Id": "acme-corp",
    },
    json={"message": "Hello, agent!"},
)

O agente recebe o seguinte dicionário depois que você executa o código anterior:

{"authorization": "my-user-id", "tenant-id": "acme-corp"}

Leia cabeçalhos no seu agente

Use o método get_current_custom_headers() de agent_engine_runner_shared dentro de qualquer ferramenta para acessar os cabeçalhos que o API Gateway encaminhou ao agente. O seguinte código Python mostra como usar get_current_custom_headers() para acessar os cabeçalhos encaminhados:

from agent_engine_sdk_langgraph import App
from agent_engine_runner_shared import get_current_custom_headers
app = App(app_name="My Agent")
@app.tool(is_local=True)
def call_external_api(query: str) -> str:
    """Call an external API using the caller's user ID."""
    headers = get_current_custom_headers()
    user_id = headers.get("authorization", "")
    tenant = headers.get("tenant-id", "")
    response = httpx.get(
        "https://api.example.com/data",
        headers={"Authorization": user_id, "X-Tenant-Id": tenant},
        params={"q": query},
    )
    return response.text

O método get_current_custom_headers() retorna um dict[str, str]. Se o gateway não enviar nenhum cabeçalho personalizado, o método retornará um dicionário vazio.

Retomar solicitações

O encaminhamento de cabeçalhos personalizados também funciona com solicitações de currículo. Como o Atlas Agent Engine não persiste cabeçalhos personalizados, você deve reenviar os mesmos cabeçalhos X-Mdb-Agent-Engine-Custom- ao retomar uma execução suspensa. Para obter um exemplo de solicitação de retomada que encaminha cabeçalhos personalizados, consulte Usar a API no guiaHuman-in-the-Loop.

Cancelar uma sessão

Para cancelar uma execução em andamento, envie uma solicitação POST para o endpoint /api/v1/projects/{project_id}/executions/{execution_id}/cancel e defina o parâmetro de query workspace_id. A solicitação não recebe um corpo.

Selecione a guia do idioma de sua preferência para ver um exemplo de cancelamento de uma execução:

curl -X POST "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/executions/$EXECUTION_ID/cancel?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $API_KEY"

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/executions/{execution_id}/cancel",
    params={"workspace_id": workspace_id},
    headers={"Authorization": f"Bearer {api_key}"},
)

A resposta se assemelha à seguinte saída:

{
  "execution_id": "string",
  "cancelled": true,
  "status": "cancelled"
}

O campo cancelled informa se esta solicitação definiu o status de execução para cancelled. O valor do campo é true para uma execução cancelled e false quando a solicitação não fez a transição da execução porque já havia atingido um status de terminal, incluindo cancelled de uma solicitação anterior. Quando o valor do campo é false, o campo status relata o status do terminal registrado.

Quando você cancela uma execução, o Atlas Agent Engine faz o seguinte:

• Cancela chamadas de ferramentas ou LLM em andamento e desmonta a sandbox do agente e a sandbox de ferramentas da sessão e libera o slot de capacidade. Uma nova execução pode reutilizar o slot.

• Cancela todas as outras execuções ao vivo na mesma sessão, incluindo execuções de agente profundo e agente a agente que são filhas da execução de destino.

• Termina um fluxo de resposta aberto em vez de deixar o fluxo aberto até que ele expire.

• Cobrança o tempo de execução que a sessão acumulou até o cancelamento.

Parar uma corrida no playground

Você também pode interromper uma execução na interface do usuário do Playground em vez de chamar o ponto de extremidade da API cancel. Interromper uma corrida a partir do Playground tem o mesmo efeito que cancelar a sessão. Para saber mais, consulte Cancelar uma sessão.

Para interromper uma execução do Playground, execute as seguintes etapas:

Interromper uma ferramenta ou chamada LLM

A interrupção de uma ferramenta ou chamada LLM interrompe apenas essa chamada. A sessão permanece ativa e o agente continua sua execução a partir do resultado interrompido. Interrompa uma chamada quando uma única chamada estiver presa ou indesejável e você não quiser cancelar a sessão inteira.

Para interromper uma chamada, envie uma solicitação de POST para o ponto de extremidade da API /api/v1/projects/{project_id}/executions/{execution_id}/interrupt. A solicitação usa os seguintes parâmetros:

Selecione a guia do seu idioma preferido para ver um exemplo de interrupção de uma ferramenta ou chamada LLM:

curl -X POST "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/executions/$EXECUTION_ID/interrupt?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_number": 12}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/executions/{execution_id}/interrupt",
    params={"workspace_id": workspace_id},
    headers={"Authorization": f"Bearer {api_key}"},
    json={"step_number": 12},
)

A resposta se assemelha à seguinte saída:

{
  "execution_id": "string",
  "interrupted": true,
  "interrupted_steps": [ 12 ],
  "pending": false,
  "outcome": "aborted"
}

O campo outcome descreve o resultado da solicitação de interrupção e retorna um dos seguintes valores:

A interrupção de uma chamada é idempotente e não altera o status de execução. Se você interromper todas as chamadas em uma etapa, o agente encerrará essa chamada em vez de tentar novamente as chamadas. Se você interromper apenas algumas das chamadas em uma etapa, o agente continuará normalmente.

Marcar uma sessão como encerrada do seu agente

Uma sessão mantém a sandbox do agente e a sandbox da ferramenta até que o tempo limite ocioso expire. Se você marcar uma sessão como concluída, seu agente poderá liberar essa computação imediatamente em vez de esperar o tempo limite.

Selecione a guia do seu idioma preferido para ver um exemplo de marcação de uma sessão concluída pelo seu agente:

status = app.finish_session()

const status = app.finishSession();

A curva atual continua em execução e retorna seu resultado. Após a conclusão da vez, o Mecanismo do Atlas cancela quaisquer execuções do subagente ativas e libera os pods da sessão.

O método retorna um dos seguintes valores:

O método não gera um erro nem lança uma exceção quando não há sessão para concluir.

Uma reviravolta que suspende a análise humana ou falha mantém seus recursos para que você possa retomá-la e diagnosticá-la. Essa sessão retorna ao tempo limite ocioso. Para saber mais sobre os tempos limite ociosos, consulte Erros completos do pool.

Sintaxe do comando

agentengine invoke [message] [flags]
agentengine invoke --file <path> [flags]

A tabela a seguir descreve os sinalizadores disponíveis:

Exemplos

O seguinte comando invoca o agente com uma única mensagem:

agentengine invoke "What can you do?"

O comando a seguir transmite a resposta do agente conforme ela é produzida:

agentengine invoke --stream "Draft a release note"

O seguinte comando retoma ou continua uma sessão nomeada:

agentengine invoke --session my-session "Follow up question"

O comando a seguir lê uma mensagem de um arquivo e gera JSON bruto:

cat prompt.txt | agentengine invoke --json

Comandos de carga útil interativos

Ao executar o agentengine invoke no modo interativo, você pode gerenciar a carga útil entre as voltas usando um dos seguintes comandos:

Análise interativa do HITL

Quando um agente suspende a revisão de humanos no loop (HITL) no modo interativo, a CLI imprime o contexto da suspensão e solicita uma decisão in-line. Para saber como a CLI apresenta o prompt de revisão e como retomar a execução,consulte Usar a CLI no guiaHuman-in-the-Loop.