Integrar o agente

O administrador entrega ao desenvolvedor o arquivo <agente>.chokepoint.json (Identidade do agente). Com ele, o agente faz dois passos: troca o token da pessoa por um token Xokepoint e usa esse token nas tool calls.

1. O token exchangeCopiar link da seção

O agente chama o token_endpoint do arquivo com o grant do RFC 8693 e se autentica com private_key_jwt (RFC 7523):

POST <token_endpoint>
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<token da pessoa, emitido pelo IdP>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&client_id=<client_id>
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<JWT assinado com private_key>

A client_assertion é um JWT curto assinado com a private_key do arquivo, com iss e sub iguais ao client_id, aud igual ao issuer ou ao token_endpoint do arquivo, um jti único e um exp próximo. O kid do arquivo vai no cabeçalho do JWT. Um jti é aceito uma vez só; reusá-lo falha com invalid_client.

A resposta traz um access_token de no máximo 5 minutos. Quando ele vence, o agente faz a troca de novo com um token da pessoa válido. Uma troca recusada responde invalid_client (a chave não confere) ou invalid_grant (o token da pessoa é inválido ou venceu, ou a pessoa não delegou ao agente), com o código Reference da recusa em error_description:

{"error":"invalid_grant","error_description":"Reference x4av-75q6."}

Registre o código no log e mande para o time de segurança: o Quick incident abre essa recusa com o motivo detalhado. A resposta nunca traz o motivo.

Para dar a uma instância em execução limites mais estreitos que a política do agente, adicione authorization_details na mesma requisição, por exemplo [{"type":"chokepoint_tool_call","server_id":"<server>","tool":"refund_payment","limits":{"max_amount":100}}] (Limites da instância). Envie de novo a cada renovação: os limites não são lembrados entre trocas. Não envie actor_token, audience, resource nem scope; o AS os recusa (O que a troca não aceita).

2. As tool callsCopiar link da seção

O agente usa o endereço MCP do server no Xokepoint, com o token no cabeçalho:

POST /api/v1/mcp/<workspace>/<ambiente>/<server>
Authorization: Bearer <access_token do Xokepoint>
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18

O corpo é o JSON-RPC normal do MCP. Uma chamada negada volta como erro JSON-RPC de acesso negado, sem execução; o agente deve tratá-la como resposta, não como falha de rede (Semântica de falha). O erro traz o código Reference da chamada negada, na mensagem que os harnesses mostram e em data para programas:

{"jsonrpc":"2.0","id":7,"error":{"code":-32001,"message":"Access denied. Reference bmbo-2573.","data":{"reference":"bmbo-2573"}}}

Registre data.reference no log. Com ele, o Quick incident abre a chamada e o passo que a negou. Uma tool que não foi revisada responde HTTP 403 tool_unavailable, também com reference no corpo.

O token do IdP nunca é usado direto nas chamadas. O Xokepoint recusa com 401 um token que ele não emitiu. Para um harness de código, que entra pelo navegador em vez de um arquivo de chave, veja Conectar um harness de código.