Referência da API do NextPDF Connect

Visão geral

Esta página é a referência em nível de símbolo do servidor NextPDF Connect (nextpdf/server). Ela lista cada ferramenta pelo nome de ferramenta registrado e pela classe de implementação, e documenta o serviço gRPC NextPDFConnect, incluindo seus métodos de Chamada de Procedimento Remoto (RPC) e as mensagens de requisição e resposta. Ela também define o contrato de autenticação, erros e limites de taxa compartilhado por todos os transportes.

O servidor expõe um único registro de ferramentas por três transportes: Model Context Protocol (MCP) sobre entrada e saída padrão, uma Interface de Programação de Aplicações (API) de Transferência de Estado Representacional (REST) e gRPC. Cada transporte documenta seus detalhes de protocolo em uma página separada: consulte Transporte MCP, Transporte REST e Transporte gRPC. Esta página cataloga os símbolos que esses transportes carregam.

Os nomes das ferramentas, as classes e os níveis de risco são lidos das implementações das ferramentas em src/Tools/. O número de ferramentas expostas por uma implantação é uma propriedade em tempo de execução; consulte Catálogo de ferramentas. Inicialização e descoberta explica a resolução de níveis.

Disponibilidade dos transportes

Uma ferramenta fica disponível por meio de cada transporte que a implantação executa. Os transportes são executados como processos independentes; iniciar um não inicia os outros.

Transporte	Ponto de entrada	Formato de protocolo	Autenticação
MCP	bin/nextpdf-mcp	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 sobre stdio	Limite do processo do sistema operacional (sem chave de API)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Chave de API Bearer no cabeçalho Authorization da requisição
gRPC	bin/nextpdf-grpc	Protocol Buffers, pacote nextpdf.connect.v1	Token Bearer nos metadados de chamada authorization da requisição

No MCP, você chama uma ferramenta com tools/call e o nome de ferramenta registrado. No REST e no gRPC, você alcança os mesmos recursos do mecanismo por meio das superfícies de renderização, operação e capacidade; consulte a tabela de rotas em Transporte REST e a tabela de RPC em Transporte gRPC.

Autenticação e nível de risco

Autenticação por chave de API

Os transportes REST e gRPC exigem uma chave de API Bearer em cada requisição, exceto nas sondas de saúde não autenticadas. Uma chave tem o formato npk_live_{kid}_{secret}: o kid é um identificador de oito caracteres para busca de registro, e o segredo carrega a entropia. O servidor armazena apenas um resumo SHA-256 da chave e compara o token apresentado em tempo constante, de modo que uma chave inválida não revela nada por temporização. O REST lê o token do cabeçalho Authorization: Bearer …; o gRPC lê o mesmo token dos metadados de chamada authorization. O transporte stdio do MCP não tem chave de API porque é um subprocesso local confiável para o cliente que o inicia. Segurança e operações documenta o modelo de autenticação completo.

Os quatro níveis de risco

Cada ferramenta declara um entre quatro níveis de risco ordenados, definidos pelo enum RiskLevel em src/Config/RiskLevel.php.

Nível	Caso do enum	Valor	Efeito
Safe	RiskLevel::Safe	0	Somente leitura, sem efeitos colaterais. Executa automaticamente.
Caution	RiskLevel::Caution	1	Cria ou modifica estado em memória. Executa automaticamente, com registro de auditoria.
Review	RiskLevel::Review	2	Produz uma saída que poderia ser usada indevidamente. Executa automaticamente, com registro de auditoria.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Destrutivo, jurídico ou crítico para a privacidade. Requer confirmação humana.

O risco efetivo de uma ferramenta vem de exatamente dois lugares: a própria declaração riskLevel() da ferramenta e uma substituição opcional na configuração do operador, que só pode elevar o risco, nunca rebaixar uma ferramenta ApprovalRequired. Consulte Níveis de risco HITL e Configuração.

Como os tokens de aprovação fluem

Quando você invoca uma ferramenta ApprovalRequired sem um token válido, o ConfirmationGate (src/Mcp/ConfirmationGate.php) retorna um token de desafio de uso único em vez de executar a ferramenta. O agente repassa o desafio a um humano e, em seguida, reinvoca a mesma ferramenta com o token emitido no argumento _confirmation_token. O token vincula o nome da ferramenta, um nonce aleatório e um tempo de vida (TTL) de 300 segundos. Ele não vincula os argumentos e não é uma credencial de autenticação. No REST, a chave de API Bearer ainda autentica a requisição, e o mesmo gate é executado no executor de ferramentas compartilhado antes da operação protegida. No gRPC, o mesmo gate é executado antes da operação despachada. O mecanismo de desafio e token é idêntico em todos os transportes.

Ferramentas e endpoints

A tabela documenta cada ferramenta pelo nome de ferramenta registrado (coluna Símbolo) e pela classe de implementação. As ferramentas são agrupadas por nível e categoria. Todas as classes de Árvore de Sintaxe Abstrata (AST) e de mutação residem em src/Tools/Ast e src/Tools/Ast/Mutation; a classe de extração reside em src/Tools/Extraction; as demais classes residem em src/Tools/Core.

Ferramentas de documento core

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
create_pdf	page_size (padrão A4), orientation (portrait/landscape), title, author; nenhum obrigatório.	Cria um documento em memória e uma página; define os metadados quando fornecidos.	JSON com document_id, page_count, page_size, orientation.	Retorna um resultado de erro com a mensagem do mecanismo em caso de falha.	Classe CreatePdfTool. Risco RiskLevel::Caution. Nível core. O document_id retornado alimenta cada operação subsequente.
add_page	document_id (obrigatório), tamanho de página e orientação opcionais.	Anexa uma página ao documento.	JSON com a nova contagem de páginas.	Resultado de erro quando o document_id é desconhecido.	Classe AddPageTool. Risco RiskLevel::Caution. Nível core.
add_text	document_id (obrigatório), text (obrigatório), posição e estilo opcionais.	Adiciona texto ao documento.	Resumo do estado do documento em JSON.	Resultado de erro quando o document_id é desconhecido.	Classe AddTextTool. Risco RiskLevel::Caution. Nível core.
add_image	document_id (obrigatório), source (obrigatório: caminho de arquivo ou base64), posicionamento opcional.	Adiciona uma imagem a partir de um caminho ou de dados base64.	Resumo do estado do documento em JSON.	Resultado de erro em caso de origem ilegível ou document_id desconhecido.	Classe AddImageTool. Risco RiskLevel::Caution. Nível core.
add_table	document_id (obrigatório), html (obrigatório).	Renderiza uma tabela em Hypertext Markup Language (HTML) no documento.	Resumo do estado do documento em JSON.	Resultado de erro em caso de marcação inválida ou document_id desconhecido.	Classe AddTableTool. Risco RiskLevel::Caution. Nível core.
set_font	document_id (obrigatório), family (obrigatório), tamanho e estilo opcionais.	Define a fonte para as operações de texto subsequentes.	Confirmação da fonte ativa em JSON.	Resultado de erro em caso de fonte desconhecida ou de document_id desconhecido.	Classe SetFontTool. Risco RiskLevel::Caution. Nível core.
output_pdf	document_id (obrigatório), file_path (opcional), destroy (padrão true).	Finaliza o documento; grava em file_path, ou retorna base64 quando omitido; destrói o documento por padrão.	JSON com file_path e file_size, ou base64 e file_size.	Resultado de erro quando o document_id é desconhecido; falha na contenção de caminho ao gravar fora do diretório base.	Classe OutputPdfTool. Risco RiskLevel::ApprovalRequired. Nível core. Gravar um arquivo passa pelo gate de confirmação; o modo base64 não.
preview_layout	document_id (obrigatório).	Retorna um resumo do layout sem renderizar o PDF final.	Resumo do layout em JSON.	Resultado de erro quando o document_id é desconhecido.	Classe PreviewLayoutTool. Risco RiskLevel::Safe. Nível core.
parse_pdf	document_id (obrigatório).	Inspeciona metadados estruturais: contagem de páginas, fontes, imagens, criptografia e Dicionário de Informações (Info Dictionary).	Metadados estruturais em JSON.	Resultado de erro em um documento malformado.	Classe ParsePdfTool. Risco RiskLevel::Safe. Nível core. Só é registrado quando NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED é true ou 1.

Ferramentas de diagnóstico core

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
diagnostic.doctor	nenhum.	Executa uma verificação de saúde e retorna diagnósticos estruturados do ambiente.	Relatório do ambiente em JSON.	Resultado de erro em uma falha de verificação interna.	Classe DiagnosticDoctorTool. Risco RiskLevel::Safe. Nível core. Não requer documento nem confirmação.
diagnostic.capabilities	nenhum.	Lista as capacidades com informações de nível e status.	Lista de capacidades em JSON.	Resultado de erro em uma falha interna.	Classe DiagnosticCapabilitiesTool. Risco RiskLevel::Safe. Nível core.
diagnostic.inspect	document_id (obrigatório).	Inspeciona um PDF e retorna metadados estruturais.	Metadados estruturais em JSON.	Resultado de erro quando o document_id é desconhecido.	Classe DiagnosticInspectTool. Risco RiskLevel::Safe. Nível core.
diagnostic.verify	document_id (obrigatório), perfil PDF/A ou PDF/UA opcional.	Verifica a integridade estrutural; opcionalmente valida PDF/A ou PDF/UA iniciando um subprocesso VeraPDF.	Relatório de verificação em JSON.	Resultado de erro em caso de falha de subprocesso, timeout ou entrada de tamanho excessivo.	Classe DiagnosticVerifyTool. Risco RiskLevel::Caution. Nível core. A entrada é limitada a 50 mebibytes (MiB).

Ferramenta de código de barras core

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
generate_barcode	payload (obrigatório), format (por exemplo QR Code, DataMatrix).	Gera uma matriz de módulos de código de barras bidimensional para o payload.	Matriz de módulos em JSON.	Resultado de erro em caso de format sem suporte ou payload inválido.	Classe BarcodeTool. Risco RiskLevel::Caution. Nível core. BarcodeTool só é registrado quando o registro de codificadores barcode do core está presente no nextpdf/core instalado; o nome de ferramenta registrado é generate_barcode.

Ferramentas de privacidade Enterprise

Essas ferramentas encapsulam classes de privacidade Enterprise e são registradas no nível Enterprise apenas quando essas classes podem ser carregadas automaticamente. Elas operam sobre conteúdo em texto simples.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
redact_pdf	content (obrigatório), opções de detecção opcionais.	Aplica redação destrutiva a informações de identificação pessoal (PII) em conteúdo de texto simples usando o mecanismo de redação Enterprise.	JSON com o conteúdo redigido e um hash SHA-256.	Resultado de erro quando as classes Enterprise estão ausentes ou a detecção falha.	Classe RedactPdfTool. Risco RiskLevel::Review. Nível enterprise.
deidentify_pdf	content (obrigatório), strategy (redigir ou suprimir).	Aplica uma estratégia sistemática de desidentificação a conteúdo de texto simples usando o desidentificador Enterprise.	JSON com o conteúdo desidentificado.	Resultado de erro quando as classes Enterprise estão ausentes.	Classe DeIdentifyPdfTool. Risco RiskLevel::Review. Nível enterprise.
zone_redact_pdf	content (obrigatório), zones (página e lista de retângulos normalizados).	Aplica redações de zona baseadas em coordenadas usando o mecanismo de redação Enterprise.	JSON com o conteúdo redigido.	Resultado de erro em caso de zona inválida ou ausência das classes Enterprise.	Classe ZoneRedactionTool. Risco RiskLevel::Review. Nível enterprise.

Ferramentas de leitura de árvore de sintaxe abstrata (AST)

Essas ferramentas acompanham o servidor, são registradas no nível Pro e são controladas por NEXTPDF_AST_TOOLS_ENABLED (habilitado por padrão). Elas são somente leitura.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
get_document_ast	pdf_data (obrigatório).	Constrói uma AST semântica: uma árvore de nós completa com âncoras de citação para cada elemento estrutural.	Árvore de nós em JSON, mais uma ETag para controle de concorrência.	Resultado de erro em um documento malformado.	Classe GetDocumentAstTool. Risco RiskLevel::Safe. Nível pro.
get_ast_node	pdf_data (obrigatório), node_id (obrigatório).	Recupera um único nó da AST e todos os seus filhos.	Nó em JSON com filhos.	Resultado de erro em um node_id desconhecido.	Classe GetAstNodeTool. Risco RiskLevel::Safe. Nível pro.
get_ast_diff	original_pdf_data (obrigatório), modified_pdf_data (obrigatório).	Calcula a diferença estrutural entre dois documentos comparando suas ASTs semânticas.	JSON com nós adicionados, removidos e alterados.	Resultado de erro em um documento de entrada malformado.	Classe GetAstDiffTool. Risco RiskLevel::Safe. Nível pro.
search_ast_nodes	pdf_data (obrigatório), filtros opcionais de tipo, índice de página e texto.	Pesquisa nós da AST por tipo, índice de página ou conteúdo de texto.	Lista plana de nós correspondentes em JSON, com filhos rasos.	Resultado de erro em um documento malformado.	Classe SearchAstNodesTool. Risco RiskLevel::Safe. Nível pro.
extract_cited_text	pdf_data (obrigatório), headings_only opcional.	Extrai blocos de texto com âncoras de citação (página, caixa delimitadora, confiança).	Blocos de texto citados em JSON.	Resultado de erro em um documento malformado.	Classe ExtractCitedTextTool. Risco RiskLevel::Safe. Nível pro. Categoria ast.
extract_cited_tables	pdf_data (obrigatório).	Extrai blocos de tabela com âncoras de citação; retorna uma matriz de células ordenadas por linha para cada nó de Tabela.	Matrizes de tabela em JSON com âncoras.	Resultado de erro em um documento malformado.	Classe ExtractCitedTablesTool. Risco RiskLevel::Safe. Nível pro. Categoria extraction.

Ferramentas de mutação de AST

Essas ferramentas acompanham o servidor, são registradas no nível Pro e são controladas por NEXTPDF_MUTATION_TOOLS_ENABLED (habilitado por padrão). Todas as quatro são ApprovalRequired e usam controle de concorrência otimista (OCC) por meio de uma ETag.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (todos obrigatórios).	Aplica um lote de mutações atomicamente; reproduz o resultado em cache para um idempotency_key repetido.	JSON com o PDF mutado e uma nova ETag.	Conflito de OCC quando a ETag está desatualizada; erro de validação em uma mutação malformada.	Classe ApplyAstMutationsTool. Risco RiskLevel::ApprovalRequired. Nível pro.
delete_ast_node	pdf_data, node_id, etag (todos obrigatórios).	Remove um nó em modo de sobreposição (o conteúdo original é coberto, não fisicamente excluído).	JSON com o PDF modificado e uma nova ETag.	Conflito de OCC quando a ETag está desatualizada; erro em um node_id desconhecido.	Classe DeleteAstNodeTool. Risco RiskLevel::ApprovalRequired. Nível pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (todos obrigatórios).	Insere um novo nó como filho do nó pai na posição especificada.	JSON com o PDF modificado e uma nova ETag.	Conflito de OCC quando a ETag está desatualizada; erro de validação em um nó malformado.	Classe InsertAstNodeTool. Risco RiskLevel::ApprovalRequired. Nível pro.
update_ast_node	pdf_data, node_id, etag, updates (todos obrigatórios).	Atualiza o conteúdo de texto de um nó.	JSON com o PDF modificado e uma nova ETag.	Conflito de OCC quando a ETag está desatualizada; erro em um node_id desconhecido.	Classe UpdateAstNodeTool. Risco RiskLevel::ApprovalRequired. Nível pro.

Esquema de requisição e resposta

O transporte gRPC define o esquema tipado do servidor no pacote Protocol Buffers nextpdf.connect.v1, em proto/nextpdf/connect/v1/*.proto. O serviço e as mensagens são os símbolos canônicos do esquema.

Serviço NextPDFConnect

O serviço NextPDFConnect expõe RPCs unários e de streaming do servidor. Os símbolos do esquema são os nomes dos métodos RPC e as mensagens de requisição e resposta que eles carregam.

RPC	Mensagem de requisição	Mensagem de resposta	Formato
Render	RenderRequest	RenderResponse	Unário. Renderização síncrona sem estado.
RenderStream	RenderRequest	RenderChunk (stream)	Streaming do servidor. Renderização entregue como blocos ordenados.
SubmitJob	SubmitJobRequest	JobResponse	Unário. Envia um trabalho de renderização assíncrono.
GetJobStatus	GetJobStatusRequest	JobResponse	Unário. Consulta o status do trabalho.
GetJobResult	GetJobResultRequest	RenderResponse	Unário. Baixa um resultado concluído.
GetJobResultStream	GetJobResultRequest	RenderChunk (stream)	Streaming do servidor. Baixa um resultado concluído como blocos.
CancelJob	CancelJobRequest	JobResponse	Unário. Cancela ou exclui um trabalho.
CreateSession	CreateSessionRequest	SessionResponse	Unário. Cria uma sessão de construção de documento.
GetSession	GetSessionRequest	SessionResponse	Unário. Obtém os metadados da sessão.
DestroySession	DestroySessionRequest	DestroySessionResponse	Unário. Destrói uma sessão e seu documento.
SessionOperation	SessionOperationRequest	SessionResponse	Unário. Executa uma operação em um documento de sessão.
SessionRender	SessionRenderRequest	RenderResponse	Unário. Renderiza um documento de sessão em PDF.
SessionRenderStream	SessionRenderRequest	RenderChunk (stream)	Streaming do servidor. Renderiza um documento de sessão como blocos.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unário. Executa uma operação de capacidade controlada por nível.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unário. Lista as capacidades disponíveis para o cliente autenticado.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unário. Sonda de vivacidade.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unário. Sonda de prontidão.

Símbolos de mensagem

As mensagens de requisição e resposta são os símbolos estruturais do esquema. As mensagens de renderização, RenderRequest, RenderResponse e o streaming RenderChunk, carregam o tamanho da página, a orientação, as operações ordenadas e os bytes de PDF resultantes. As mensagens de trabalho, SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest e JobResponse, modelam o ciclo de vida do trabalho assíncrono, com os metadados do trabalho mantidos na mensagem JobData. As mensagens de sessão, CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest e SessionRenderRequest, modelam o ciclo de vida da sessão com estado, com os metadados da sessão mantidos na mensagem SessionData. As mensagens de capacidade, CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest e GetCapabilitiesResponse, carregam o despacho e a introspecção de operações controladas por nível. As mensagens de sistema, HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest e ReadinessCheckResponse, carregam o status de vivacidade e de prontidão.

Os arquivos .proto distribuídos são o contrato de protocolo de referência; consulte a referência do transporte gRPC em Transporte gRPC.

Modelo de erro

O servidor relata falhas com o mecanismo de erro nativo de cada transporte. Cada transporte preserva a mesma condição lógica; apenas a codificação difere.

MCP

Os erros do MCP são objetos de erro JSON-RPC 2.0. Um método desconhecido retorna método-não-encontrado (-32601); uma mensagem que não é JSON-RPC válido retorna requisição-inválida (-32600); uma entrada não analisável retorna erro-de-análise (-32700). Uma ferramenta com falha retorna uma resposta JSON-RPC bem-sucedida cujo conteúdo marca o erro, em vez de um erro em nível de transporte, para que o agente possa ler a mensagem. Um desafio de confirmação para uma ferramenta ApprovalRequired também é uma resposta bem-sucedida, não um erro.

REST

O REST usa códigos de status do Hypertext Transfer Protocol (HTTP) com a semântica definida pela RFC 9110. Um 200 carrega o resultado; um 400 é retornado quando um campo de requisição falha na validação de formato; um 401 é retornado quando nenhuma chave de API válida é apresentada e carrega um cabeçalho de desafio WWW-Authenticate: Bearer; um 403 é retornado quando o nível de uma chave válida não dá direito à operação; um 404 é retornado quando uma rota controlada por nível não está registrada porque seu pacote está ausente. Os corpos de erro legíveis por máquina são documentos Problem Details conforme a RFC 9457, servidos com o tipo de mídia application/problem+json e um type Identificador Uniforme de Recursos (URI) estável para cada condição. As falhas de validação em nível de campo são listadas no corpo. Como medida de proteção contra travessia de caminho, um document_id que não corresponde ao padrão doc_[a-f0-9]{24} é rejeitado com 400 antes de a ferramenta ser executada. Transporte REST documenta o pipeline de middleware do REST e a tabela de rotas.

gRPC

O gRPC usa códigos de status gRPC padrão. Um token ausente, malformado, desconhecido, desabilitado ou expirado faz a chamada falhar com UNAUTHENTICATED em vez de um status HTTP. O detalhe rico de erro espelha o formato Problem Details do REST e é carregado nos detalhes de status do gRPC, de modo que o type URI do erro é consistente em todos os transportes.

Consulte também a RFC 9110 (HTTP Semantics) para a semântica dos códigos de status e a RFC 9457 (Problem Details for HTTP APIs) para o formato do corpo de erro.

• RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
• RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

Limites de taxa e cotas

O transporte REST aplica limitação de taxa por endereço de Protocolo de Internet (por IP) e por cliente em seu pipeline de middleware, além de limites de tamanho de corpo e de payload por nível e um timeout por requisição. Esses limites são valores de configuração, não constantes codificadas:

• Os limites de payload por nível (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) e os timeouts correspondentes se aplicam no REST de acordo com o nível da chave autenticada. Consulte Configuração.
• O armazenamento de documentos em memória é limitado por max_documents (padrão 50) e document_ttl (padrão 1800 segundos).
• O estado de limite de taxa e de idempotência é por trabalhador, a menos que NEXTPDF_REDIS_HOST esteja configurado para um armazenamento compartilhado. Consulte Implantação.

Quando os armazenamentos de limite de taxa e de idempotência são compartilhados, submissões de trabalho assíncrono idênticas e repetidas são deduplicadas pelo idempotency_key. O transporte MCP processa uma requisição por vez por pipes e deduplica um id de requisição repetido a partir de um buffer de 64 entradas, em vez de aplicar limites de taxa de rede.

Notas de desenvolvimento

• Leia os nomes das ferramentas, as classes e os níveis de risco do código-fonte em src/Tools/; não presuma um total fixo. Consulte o servidor em execução para obter a contagem autoritativa, conforme mostrado em Catálogo de ferramentas.
• Regenere os stubs de cliente gRPC a partir dos arquivos proto/nextpdf/connect/v1/*.proto distribuídos; o pacote e o namespace são nextpdf.connect.v1. Não edite as classes de mensagem geradas manualmente.
• Uma ferramenta ApprovalRequired responde com um desafio de confirmação na primeira chamada. Construa o caminho de repetição — repasse o desafio e, em seguida, reinvoque com _confirmation_token — antes de você lançar uma integração que aciona output_pdf ou qualquer ferramenta de mutação.
• Uma rota ou capacidade controlada por nível que não está instalada não é uma falha de autenticação: o REST retorna 404 para uma rota ausente, e o ExecuteCapability do gRPC relata a operação como indisponível. Trate um nível Pro ou Enterprise ausente como operação esperada, não como uma falha.
• Mantenha as chaves de API fora do controle de versão; monte-as a partir de um arquivo de segredo e prefira o armazenamento de chaves em arquivo com recarregamento a quente, para que a rotação não precise de reinício. Consulte Segurança e operações.

Veja também

• Guia do desenvolvedor — arquitetura, ciclo de vida, pontos de extensão e a lista de verificação de testes
• Catálogo de ferramentas — o conjunto verificado de ferramentas core e a contagem em tempo de execução
• Níveis de risco HITL — o modelo de risco e o desafio de confirmação
• Transporte MCP · Transporte REST · Transporte gRPC — detalhes de protocolo por transporte
• Segurança e operações — autenticação, segurança de transporte e o modelo de ameaças