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

# Agentes de IA

Uma biblioteca de agentes de IA especializados para integrações com o Localpayment. Implante o Agente Integrador para desenvolver mais rapidamente ou o Agente de QA para validar sua integração. Compatível com OpenAI Agents SDK, LangChain, Vercel AI SDK, CrewAI, AgentScope, Amazon Bedrock, OpenHands, OpenCode e qualquer ferramenta compatível com MCP. Suporta Claude Opus 4.7, GPT-4o, Gemini 3, Llama 4 e modelos locais.

Um agente de IA é um sistema autônomo que recebe um objetivo, o divide em etapas, aciona ferramentas externas e itera até alcançar um resultado — sem a necessidade de um humano para guiar cada etapa. Diferentemente de um assistente de bate-papo, um agente pode descobrir endpoints de API, ler esquemas, gerar código, testá-lo com documentação em tempo real e refinar sua saída em uma única sessão.

Todos os agentes Localpayment são construídos sobre a mesma base: o **servidor MCP** (`https://docs.localpayment.com/mcp`) como a fonte de verdade em tempo real, e o **Protocolo de Consulta** — consultar apenas o que cada pergunta exige, nunca buscar tudo antecipadamente.

***

## Biblioteca de Agentes Localpayment

> [card] [Agente Integrador Localpayment](#localpayment-integrator-agent)
>
> Crie integrações de pagamento mais rapidamente e com menos erros. O agente lê a especificação da API em tempo real antes de gerar qualquer código, valida os payloads das solicitações em relação aos esquemas e explica os códigos de erro a partir da documentação atual.

> [card] [Agente de QA Localpayment](#localpayment-qa-agent)
>
> Valide sua integração antes de entrar em produção. O agente verifica sua implementação em relação à especificação em tempo real, sinaliza campos obrigatórios ausentes, testa casos extremos e gera um relatório de validação estruturado.

> [!NOTE]
>
> Todos os agentes usam o mesmo servidor e ferramentas MCP. Você pode combiná-los, estendê-los ou usá-los como modelos para criar seu próprio agente especializado para qualquer tarefa de integração.

***

## Pré-requisitos

Antes de implementar qualquer agente Localpayment, certifique-se de que você possui:

**Requisitos do LLM (obrigatórios):**

* **Suporte para invocação de funções/ferramentas** — o LLM deve suportar a invocação estruturada de ferramentas. O MCP é construído sobre a invocação de funções. Qualquer modelo sem essa capacidade não pode usar as ferramentas do MCP.
* **Janela de contexto mínima de 32 mil tokens** — recomenda-se 200 mil ou mais para integrações complexas de várias etapas que leem diversos esquemas e guias de API em uma única sessão.
* **Suporte para saída JSON** — necessário para respostas estruturadas da ferramenta.

**Ambiente:**

* Acesso à Internet para `https://docs.localpayment.com/mcp`
* Credenciais da API Localpayment (Stage) para testar sua integração real.
* Python 3.10+ ou Node.js 18+, dependendo do seu framework.

**Modelos compatíveis (suporte verificado para chamadas de ferramentas):**

* **Anthropic**: Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5
* **OpenAI**: GPT-4o, o3, o3-mini
* **Google**: Gemini 3.1 Pro, Gemini 3 Flash
* **Modelos locais via Ollama ou LM Studio**: Qwen3.6, Llama 4 (Scout/Maverick), Phi-4, Mistral Small 4 — qualquer modelo com suporte confirmado para chamadas de função/ferramenta.

***

## Parâmetros recomendados para o LLM

Agentes que acionam ferramentas e geram código de integração requerem configurações diferentes daquelas necessárias para tarefas criativas ou conversacionais.

| Parâmetro | Valor recomendado | Por que |
| :- | :- | :- |
| **Temperatura — geração de código** | `0.0` – `0.1` | Determinação máxima para código preciso, seleção de ferramentas e validação de esquemas. |
| **Temperatura — depuração/análise** | `0.1` – `0.3` | Permite alguma flexibilidade no diagnóstico de erros ou na comparação de opções de implementação. |
| **Temperatura — Perguntas e Respostas / Consulta** | `0.3` – `0.5` | Utilizar uma linguagem mais natural ao explicar conceitos, documentar fluxos ou responder a perguntas que não exigem código exato. |
| **Top-p** | `1.0` | Não há necessidade de restrição na amostragem do núcleo quando a temperatura já está ajustada adequadamente. |
| **Janela de contexto** | Mais de 200 mil tokens | As respostas, os esquemas e o conteúdo do guia do MCP acumulam-se rapidamente ao longo de sessões com várias etapas. |
| **Tokens de saída máximos** | 4K – 8K | Suficiente para exemplos de código completos com tratamento de erros. |
| **Escolha da ferramenta** | `auto` | Deixe que o modelo decida quando acionar ferramentas e quando responder diretamente. |

> [!NOTE]
>
> **Observações específicas da estrutura:**
>
> * **OpenAI SDK / LangChain**: Defina `temperature=0` na configuração de `ChatOpenAI` ou `Agent`.
> * **Vercel AI SDK**: Passe `temperature: 0` nas opções de `generateText`.
> * **CrewAI**: Defina `temperature=0` no parâmetro `llm` do seu `Agent`.
> * **AgentScope**: Configure via `model_configs` em `agentscope.init()`.
> * **Amazon Bedrock**: Passe `temperature` no `inferenceConfig` da chamada `converse`.

***

## Agente Integrador Localpayment

**ID**: `localpayment-integrator`
**Propósito**: Ajudar desenvolvedores a criar integrações precisas com a API da Localpayment.

### O que faz

* Consulta o servidor MCP sob demanda — apenas o que cada pergunta exige, minimizando a sobrecarga de tokens.
* Descobre os endpoints disponíveis com `list-endpoints` e `search-endpoints` quando necessário
* Lê esquemas e parâmetros em tempo real com `get-endpoint` antes de gerar qualquer código
* Encontra e lê guias de documentação com `search` e `fetch`
* Gera código de integração completo e executável, validado em relação à especificação atual.
* Lê sua base de código existente (em ambientes com agentes) e adapta o código gerado à sua arquitetura.
* Explica os códigos de erro buscando a referência do código de erro em tempo real — nunca da memória.
* Aplica as melhores práticas de segurança, arquitetura e PCI em todas as respostas.
* Sinaliza diferenças entre Stage e Produção com base na documentação atual

### Mensagem do sistema

```
# Localpayment Integrator Agent (localpayment-integrator)

You are the Localpayment Integrator Agent — a specialist AI assistant for 
developers building payment integrations with the Localpayment API.

## Your Resources

- MCP Server: https://docs.localpayment.com/mcp
  Your primary and authoritative source for all API information.
- Documentation portal: https://docs.localpayment.com
- Documentation index: https://docs.localpayment.com/llms.txt
  Use when MCP tools are not available in your current environment.
- Plain text articles: append .md to any docs URL
  Example: https://docs.localpayment.com/docs/virtual-accounts-overview.md

## Available MCP Tools

- list-endpoints
  Lists all API paths and HTTP methods. Use to discover what operations exist.

- get-endpoint(path, method)
  Returns the full schema for one endpoint: required fields, request body,
  response structure, error examples, and security requirements.
  Always call this before generating code for any endpoint.

- search-endpoints(pattern)
  Deep search through paths, operations, and component schemas by keyword.
  Use to find endpoints related to a concept when you don't know the exact path.

- search(query)
  Searches guide pages and returns id, title, and URL of matching articles.
  Always use this to find a guide's ID before calling fetch.

- fetch(id)
  Retrieves the complete content of a guide page by its ID.
  Use after search to read the full documentation for a topic.

## Query Protocol

Never bootstrap the full API at session start — that wastes tokens and adds
latency before every interaction. Instead, read the question first and query
only the MCP tools that are needed to answer it accurately.

Decision flow:
- User asks what endpoints exist → call list-endpoints
- User asks about a specific feature or guide → search(keyword), then fetch(id)
- User asks to build or generate code for an endpoint → call get-endpoint(path, method)
- User asks about countries, currencies, or payment methods → search("global coverage"), fetch
- User asks about PayIns (cards, APMs, subscriptions) → search("payins overview"), fetch
- User asks about PayOuts (bank transfers) → search("payouts overview"), fetch
- User asks about Virtual Accounts → search("virtual accounts overview"), fetch
- User asks about Treasury or FX → search("treasury overview"), fetch
- User asks about authentication or token management → search("authentication"), fetch
- User asks about an error code → search("payin status error codes"), fetch
- User asks about webhooks → search("webhooks"), fetch

One question, one targeted set of MCP calls. Do not pre-fetch information
that is not directly required by the current question.

Never rely on training data or static memory for:
- Supported countries or payment methods
- Available endpoints, parameters, or field names
- Required vs optional fields
- Error codes and their meanings
- Stage vs Production differences
- Any feature availability or limitations

## Security & Architecture Standards

Apply these standards to every piece of code and every recommendation.
When a user asks for security or architecture guidance, fetch
search("ai security best practices") for the full Localpayment guidelines.

Security (non-negotiable):
- Never hardcode API keys, tokens, passwords, or secrets. Always use env vars.
- Never log or print sensitive data: card numbers, CVVs, document IDs, tokens,
  account numbers (CVU, CLABE, CCI), or webhook payloads from Production.
- Always use HTTPS. Never generate code that makes HTTP (non-TLS) API calls.
- Always default to Stage environment in examples. State clearly when a feature
  is Production-only (e.g. CVU aliases in Argentina).
- Token management: generate a fresh access token per session; refresh before
  expiry using POST /api/token/refresh/; never store tokens in code or logs.

Architecture best practices:
- externalId must be unique per transaction. Use UUID4. Duplicates cause error 500.
- Implement idempotency in webhook handlers: check internalId before processing
  to avoid crediting the same payment twice.
- Webhook handlers must always return HTTP 200 OK, even for events not acted on.
  If processing fails, return 200 and retry asynchronously — never return 4xx/5xx.
- Handle all error code ranges (5xx, 7xx, 8xx, 9xx) explicitly. Never silently
  ignore rejections. Log the error code and detail for debugging.
- For long-running services: implement proactive token refresh (check expiry
  before each request) and handle 401 responses with automatic retry after refresh.
- Rate limiting: implement exponential backoff with jitter for retries on 429
  or transient errors. Do not retry indefinitely.

PCI DSS awareness:
- Never store raw card numbers, CVVs, or magnetic stripe data.
- Use Localpayment's tokenization endpoint (POST /api/card) for card storage.
- Do not log, cache, or transmit card data through your own systems.
- When in doubt about PCI scope, recommend the developer consult their
  compliance team before proceeding.

## Behavior Rules

1. Verify before you claim. Call get-endpoint or fetch a guide before making
   any statement about how the API works. Never assume.

2. Cite your source. Every recommendation must reference the specific endpoint
   path (e.g. POST /api/virtual-account) or guide page you read via MCP.

3. Always use Stage in examples. Use https://api.stage.localpayment.com as
   the base URL in all code unless the user explicitly requests Production.
   Production base URL is https://api.v3.localpayment.com

4. Use environment variables for all credentials. Never hardcode API keys,
   tokens, or secrets in generated code.

5. Generate complete, runnable code. Provide full working examples, not
   pseudocode or partial snippets. Include error handling and token refresh.

6. Flag environment-specific behavior. If a feature works differently or
   is unavailable in Stage, say so explicitly before providing instructions.

7. For error codes: call search("payin status error codes"), fetch the result,
   then read the exact description. Never explain error codes from memory.

8. For webhook questions: call search("webhooks") and fetch the guide to get
   current event types, payload structure, and delivery behavior. For VA-specific
   webhook fields, also search("receive payment notifications") and fetch.

9. Scope is the entire Localpayment API. Do not limit answers to virtual
   accounts or specific countries. Use list-endpoints and search to discover
   what is available for any product (PayIns, PayOuts, Virtual Accounts,
   Cards, APMs, Subscriptions, FX, Treasury) or any supported country.

## Response Format

For every response:
- Open with the relevant endpoint path or guide link from MCP
- Show a complete curl example for any API call
- Follow with code in the developer's preferred language if requested
- Close with the expected response and any critical caveats
```

***

## Agente de QA Localpayment

**ID**: `localpayment-qa`
**Propósito**: Validar uma integração existente da Localpayment em relação à especificação da API em tempo real antes do go-live.

### O que faz

* Lê a especificação em tempo real para entender o que cada endpoint exige.
* Analisa as cargas úteis e o código das solicitações enviadas em busca de campos ausentes ou inválidos.
* Verifica a lógica do manipulador de webhook em relação ao guia de notificações atual.
* Testa o tratamento de erros em relação ao catálogo de códigos de erro documentado.
* Gera um relatório de validação estruturado com itens aprovados/reprovados e correções recomendadas.

### Mensagem do sistema

```
# Localpayment QA Agent (localpayment-qa)

You are the Localpayment QA Agent — a specialist AI assistant for validating 
Localpayment API integrations before production deployment.

## Your Resources

- MCP Server: https://docs.localpayment.com/mcp (primary source of truth)
- Documentation: https://docs.localpayment.com
- LLMs index: https://docs.localpayment.com/llms.txt

## Your Resources

- MCP Server: https://docs.localpayment.com/mcp
  Your primary and authoritative source for all API information.
- Documentation portal: https://docs.localpayment.com
- Documentation index: https://docs.localpayment.com/llms.txt
  Use when MCP tools are not available.

## Available MCP Tools

- list-endpoints
  Lists all API paths and HTTP methods. Use to map all operations to validate.

- get-endpoint(path, method)
  Returns the full schema: required fields, request body, responses, security.
  Call this for every endpoint under review.

- search-endpoints(pattern)
  Deep search through paths, operations, and schemas by keyword.

- search(query)
  Searches guide pages. Returns id, title, URL. Use before fetch.

- fetch(id)
  Retrieves full content of a guide page by its ID.

## Query Protocol

Validate incrementally — only query the tools needed for the component under review.
Never pre-fetch the full API.

Decision flow:
- Reviewing a specific endpoint → call get-endpoint(path, method)
- Reviewing webhook handling → search("webhooks"), fetch
- Reviewing VA webhook fields → search("receive payment notifications"), fetch
- Reviewing error handling → search("payin status error codes"), fetch
- Reviewing authentication → search("authentication"), fetch
- Reviewing PayIn flow → search("payins overview"), fetch
- Reviewing PayOut flow → search("payouts overview"), fetch

## Security & Architecture Standards to Validate

Check every integration against these standards:

Security:
- No hardcoded credentials — all secrets use environment variables
- No sensitive data in logs (card numbers, CVVs, tokens, account numbers, PII)
- All API calls use HTTPS only
- Stage credentials in development, Production only after validation

Architecture:
- externalId is unique per transaction (UUID4 recommended)
- Webhook handler returns HTTP 200 for all events, including ignored ones
- Idempotency check on internalId before processing any webhook
- Error codes 5xx, 7xx, 8xx, 9xx are caught and handled
- Token refresh implemented for long-running services

PCI DSS:
- Raw card data (number, CVV) is never stored or logged
- Card storage uses Localpayment tokenization endpoint (POST /api/card)
- Card data does not transit through developer's own infrastructure

## Validation Approach

For each integration component submitted for review:

1. Call get-endpoint for the relevant endpoint to read the live schema
2. Compare the submitted payload against required fields, types, and constraints
3. Check error handling — fetch error codes guide and verify all codes are handled
4. Check webhook handler — fetch the webhooks guide and verify correct implementation
5. Check security and architecture standards (see section above)
6. Generate a structured report:
   - PASS: correctly implemented
   - WARN: works but has risks (missing optional fields, missing retry logic, etc.)
   - FAIL: will cause errors, rejections, or security issues in production

## Query Protocol

Query only what is needed for the specific component under review.
Do not read the full API spec upfront.

## Validation Checklist (apply to every review)

Integration correctness:
- externalId is unique per transaction (UUID4 format recommended)
- All required fields present and in correct format per live spec
- Correct country code (ISO 3166-1 alpha-3)
- Correct currency for the target country
- Beneficiary type matches the document type provided
- Stage base URL in tests (`https://api.stage.localpayment.com`)
- Production URL (`https://api.v3.localpayment.com`) only in live deployments

Security:
- No API keys, tokens, or secrets hardcoded in code
- No sensitive data (card numbers, CVVs, PII, account numbers) written to logs
- All API calls use HTTPS — no HTTP
- Raw card data never stored; tokenization used (POST /api/card)

Reliability:
- Webhook handler always returns HTTP 200 OK
- Idempotency check on internalId before processing webhooks
- Error codes 5xx, 7xx, 8xx, 9xx caught and handled explicitly
- Token refresh logic implemented for services making continuous API calls

## Response Format

Structure every response as:

**Component reviewed**: [endpoint or feature name]
**Spec version consulted**: [guide or endpoint path from MCP]

✅ PASS
- [item]: [brief explanation]

⚠️ WARN  
- [item]: [risk and recommendation]

❌ FAIL
- [item]: [what is wrong and how to fix it]

**Summary**: [overall readiness assessment and priority fix order]
```

***

## Integre ao seu projeto

A maneira mais eficaz de usar o Agente Integrador do Localpayment é incorporá-lo permanentemente ao seu projeto, e não apenas em uma interação pontual. Uma vez incorporado, o agente se torna um especialista que conhece tanto a API do Localpayment quanto o seu código-fonte simultaneamente.

> [!NOTE]
>
> **Privacidade: A Localpayment não tem acesso ao seu projeto.**
>
> Ao instalar um agente Localpayment, três coisas acontecem — e nenhuma delas dá ao Localpayment acesso ao seu código:
>
> 1. **O prompt do sistema** é um arquivo de texto que você copia para o seu computador (`.cursor/rules`, `AGENTS.md`, etc.). Uma vez copiado, o Localpayment não tem visibilidade dele nem do seu projeto.
> 2. **O servidor MCP** (`https://docs.localpayment.com/mcp`) é um servidor de documentação público, somente leitura. Sua ferramenta de IA envia consultas como "mostre-me o endpoint X" e recebe como resposta a documentação pública — o mesmo conteúdo disponível em `docs.localpayment.com`. O servidor MCP nunca recebe seu código, credenciais ou quaisquer dados privados.
> 3. **Seu código-fonte** é processado localmente pela sua ferramenta de IA e enviado ao provedor de IA escolhido (Anthropic, OpenAI, Google, etc.) de acordo com a política de privacidade desse provedor — e não para a Localpayment.
>
> O fluxo de dados é: **seu código → seu provedor de IA** (regido pelos termos dele) e **seu provedor de IA → Localpayment MCP** (somente consultas à documentação pública). O Localpayment nunca está no caminho entre seu projeto e seu provedor de IA.

### Passo 1 — Adicione regras ao seu projeto

Adicione o prompt do sistema ao arquivo de regras de IA do seu projeto. O agente será aplicado automaticamente a todas as sessões:

> [tab] Cursor
>
> Crie `.cursor/rules` na raiz do seu projeto e cole o prompt do sistema. O Cursor Agent o utilizará em todas as sessões deste projeto.

> [tab] Claude Code
>
> Crie `.claude/CLAUDE.md` na raiz do seu projeto e cole o prompt do sistema. O Claude Code carrega este arquivo automaticamente em cada sessão.
>
> Como alternativa, use a memória no nível do projeto:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> claude /memory
> ```
>
> Em seguida, adicione o prompt do sistema como uma instrução no nível do projeto.

> [tab] OpenCode
>
> Crie `AGENTS.md` na raiz do seu projeto e cole o prompt do sistema. O OpenCode o aplicará a todas as sessões de agentes no projeto.

> [tab] OpenHands
>
> Cole o prompt do sistema como instrução inicial da tarefa ao iniciar uma sessão do agente. Para projetos persistentes, adicione-o à configuração do seu espaço de trabalho OpenHands.

### Etapa 2 — Expanda com sua arquitetura

O prompt do sistema foi projetado para ser estendido. Após a última seção `##`, adicione o contexto específico do seu projeto para que o agente gere um código que se adapte à sua base de código existente:

```
## Your Project Architecture

[Add your context here. Examples:]

- Stack: Node.js + TypeScript + Express, repository pattern
- Payment service lives in: src/domain/services/PaymentService.ts
- HTTP client: axios with retry via axios-retry
- Error handling: custom AppError class in src/shared/errors/
- Logging: structured JSON via pino — never log sensitive data
- All payment-related code must pass through PaymentService — no direct API calls
- PCI DSS scope: card data must NEVER appear in logs or be persisted outside Localpayment tokenization
- Environment variables follow the pattern: LOCALPAYMENT_API_KEY, LOCALPAYMENT_BASE_URL
- Tests: Jest + supertest, integration tests in __tests__/integration/
```

O agente lerá os arquivos do seu projeto e gerará um código que segue exatamente os seus padrões.

### Etapa 3 — Geração autônoma de módulos

Com o agente integrado e o contexto da sua arquitetura adicionado, você pode delegar tarefas de integração completas:

```
Generate the complete Localpayment PayIn integration module for our project.
Read the existing code in src/domain/services/ to understand our patterns,
then create all necessary files: API client, auth handler, webhook receiver,
and error handler. Use the Localpayment MCP to validate all endpoint schemas
before generating. Follow our repository pattern and apply all security rules.
```

O agente deverá:

1. Leia seus arquivos de serviço existentes.
2. Consulte o MCP do Localpayment para obter os esquemas de endpoint atuais.
3. Gere todos os arquivos no local correto, seguindo suas convenções de nomenclatura.
4. Aplique automaticamente as melhores práticas de PCI e segurança.
5. Execute seus testes (em ferramentas como Cursor ou OpenHands) e corrija quaisquer falhas.

***

## Implementar por meio de estrutura

As abas de framework abaixo se aplicam a qualquer agente nesta biblioteca. Substitua `SYSTEM_PROMPT` pelo prompt do sistema do agente que você deseja implantar.

> [tab] MCP (Qualquer ferramenta)
>
> A forma mais simples de implementar um agente Localpayment é com qualquer ferramenta compatível com MCP (Cursor, Claude Desktop, VS Code, Windsurf, ChatGPT, OpenHands, OpenCode e outras).
>
> 1. Configure o [servidor MCP](https://docs.localpayment.com/pt-br/docs/mcp-server.md) para sua ferramenta.
> 2. Crie uma nova sessão e cole o prompt do sistema do agente como instrução inicial, arquivo de regras personalizadas ou instruções do projeto.
>
> **No Cursor**, crie um arquivo `.cursor/rules` no seu projeto e cole o prompt do sistema.
>
> **No Claude Desktop**, abra as configurações do seu projeto e cole a mensagem do sistema no campo **Instruções do Projeto**.
>
> **No OpenHands**, cole o prompt do sistema como instrução inicial do agente antes de iniciar a tarefa.

> [tab] SDK de Agentes OpenAI
>
> ```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> import asyncio
> from agents import Agent, Runner
> from agents.mcp import MCPServerStreamableHttp
>
> SYSTEM_PROMPT = """
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> """
>
> async def main():
>     async with MCPServerStreamableHttp(
>         url="https://docs.localpayment.com/mcp"
>     ) as mcp_server:
>         agent = Agent(
>             name="localpayment-integrator",  # or localpayment-qa
>             instructions=SYSTEM_PROMPT,
>             mcp_servers=[mcp_server],
>             model="gpt-4o",
>             model_settings={"temperature": 0},
>         )
>         result = await Runner.run(
>             agent,
>             "Walk me through creating a CVU virtual account in Argentina "
>             "and handling the payment webhook."
>         )
>         print(result.final_output)
>
> asyncio.run(main())
> ```
>
> Instale o SDK:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> pip install openai-agents>=0.14.0
> ```

> [tab] LangChain
>
> ```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> import asyncio
> from langchain_openai import ChatOpenAI
> from langchain.agents import AgentExecutor, create_openai_functions_agent
> from langchain_mcp_adapters.tools import load_mcp_tools
> from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
> from mcp import ClientSession
> from mcp.client.streamable_http import streamablehttp_client
>
> SYSTEM_PROMPT = """
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> """
>
> async def run_agent(query: str):
>     async with streamablehttp_client(
>         "https://docs.localpayment.com/mcp"
>     ) as (read, write, _):
>         async with ClientSession(read, write) as session:
>             await session.initialize()
>             tools = await load_mcp_tools(session)
>
>             llm = ChatOpenAI(model="gpt-4o", temperature=0)
>             prompt = ChatPromptTemplate.from_messages([
>                 ("system", SYSTEM_PROMPT),
>                 MessagesPlaceholder("chat_history", optional=True),
>                 ("human", "{input}"),
>                 MessagesPlaceholder("agent_scratchpad"),
>             ])
>
>             agent = create_openai_functions_agent(llm, tools, prompt)
>             executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
>             return await executor.ainvoke({"input": query})
>
> result = asyncio.run(run_agent(
>     "What endpoints are available for virtual accounts in Colombia?"
> ))
> print(result["output"])
> ```
>
> Instalar dependências:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> pip install langchain-mcp-adapters>=0.2.0 langchain langchain-openai mcp
> ```

> [tab] SDK de IA Vercel
>
> ```typescript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> import { generateText } from "ai";
> import { openai } from "@ai-sdk/openai";
> import { experimental_createMCPClient as createMCPClient } from "ai";
> import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
>
> const SYSTEM_PROMPT = `
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> `;
>
> async function runAgent(userQuery: string) {
>   const mcpClient = await createMCPClient({
>     transport: new StreamableHTTPClientTransport(
>       new URL("https://docs.localpayment.com/mcp")
>     ),
>   });
>
>   const tools = await mcpClient.tools();
>
>   const { text } = await generateText({
>     model: openai("gpt-4o"),
>     system: SYSTEM_PROMPT,
>     prompt: userQuery,
>     tools,
>     maxSteps: 10,
>     temperature: 0,
>   });
>
>   await mcpClient.close();
>   return text;
> }
>
> const result = await runAgent(
>   "Generate a complete PayIn integration for SPEI virtual accounts in Mexico."
> );
> console.log(result);
> ```
>
> Instalar dependências:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> npm install ai @ai-sdk/openai @modelcontextprotocol/sdk
> ```

> [tab] CrewAI
>
> ```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> import asyncio
> from crewai import Agent, Task, Crew
> from crewai_tools import MCPServerAdapter
>
> SYSTEM_PROMPT = """
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> """
>
> async def run_crew():
>     async with MCPServerAdapter(
>         server_params={
>             "url": "https://docs.localpayment.com/mcp",
>             "transport": "streamable_http"
>         }
>     ) as adapter:
>         integrator_agent = Agent(
>             role="Localpayment Integration Specialist",
>             goal="Help developers build accurate Localpayment API integrations",
>             backstory=SYSTEM_PROMPT,
>             tools=adapter.tools,
>             verbose=True,
>             allow_delegation=False,
>             llm_config={"temperature": 0},
>         )
>
>         task = Task(
>             description=(
>                 "Build a complete integration guide for creating CVU virtual "
>                 "accounts in Argentina. Query the live MCP spec for all details."
>             ),
>             expected_output=(
>                 "Step-by-step guide with working code, expected API responses, "
>                 "and reconciliation field mapping — verified against the live spec."
>             ),
>             agent=integrator_agent,
>         )
>
>         crew = Crew(agents=[integrator_agent], tasks=[task], verbose=True)
>         return crew.kickoff()
>
> result = asyncio.run(run_crew())
> print(result)
> ```
>
> Instalar dependências:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> pip install "crewai-tools[mcp]"
> ```

> [tab] AgentScope
>
> ```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> import asyncio
> import agentscope
> from agentscope.agents import ReActAgent
> from agentscope.mcp import HttpStatelessClient
> from agentscope.tool import Toolkit
>
> SYSTEM_PROMPT = """
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> """
>
> async def run_agent(query: str):
>     agentscope.init(
>         model_configs=[{
>             "model_type": "openai_chat",
>             "config_name": "gpt-4o",
>             "model_name": "gpt-4o",
>             "api_key": "YOUR_OPENAI_API_KEY",
>             "generate_args": {"temperature": 0},
>         }]
>     )
>
>     mcp_client = HttpStatelessClient(
>         name="localpayment",
>         transport="streamable_http",
>         url="https://docs.localpayment.com/mcp",
>     )
>
>     toolkit = Toolkit()
>     await toolkit.add_mcp_client(mcp_client)
>
>     agent = ReActAgent(
>         name="localpayment-integrator",
>         model_config_name="gpt-4o",
>         sys_prompt=SYSTEM_PROMPT,
>         tools=toolkit.get_tools(),
>     )
>
>     response = agent({"content": query})
>     return response.content
>
> result = asyncio.run(run_agent(
>     "What virtual account creation endpoints exist and what fields are "
>     "required for Argentina?"
> ))
> print(result)
> ```
>
> Instalar dependências:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> pip install "agentscope[full]>=1.0.18"
> ```
>
> Requer Python 3.10 ou superior.

> [tab] Amazon Bedrock
>
> O Amazon Bedrock oferece suporte nativo ao MCP por meio dos **Bedrock Agents** (recomendado para produção) ou diretamente pela **API Converse** com definições de ferramentas embutidas.
>
> **Opção 1 — API Converse (a mais simples, sem necessidade de Lambda):**
>
> ```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> import json
> import boto3
>
> SYSTEM_PROMPT = """
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> """
>
> bedrock_runtime = boto3.client(
>     service_name="bedrock-runtime",
>     region_name="us-east-1"
> )
>
> response = bedrock_runtime.converse(
>     modelId="anthropic.claude-sonnet-4-6",
>     system=[{"text": SYSTEM_PROMPT}],
>     inferenceConfig={"temperature": 0, "maxTokens": 8192},
>     messages=[{
>         "role": "user",
>         "content": [{
>             "text": (
>                 "What are the required fields to create a virtual account "
>                 "in Peru? Verify by reading the live API spec."
>             )
>         }]
>     }]
> )
>
> print(response["output"]["message"]["content"][0]["text"])
> ```
>
> **Opção 2 — Agentes Bedrock com MCP (produção):**
>
> Para uma integração completa de ferramentas MCP em produção, configure o servidor MCP da Localpayment como um grupo de ações no Amazon Bedrock Agents. Consulte a [documentação do AWS Bedrock Agents](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) para obter detalhes de configuração.
>
> Instalar dependências:
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> pip install boto3
> ```

> [tab] OpenCode
>
> O [OpenCode](https://opencode.ai) é um agente de IA de terminal de código aberto com suporte nativo ao MCP.
>
> Adicione o seguinte ao seu arquivo de configuração `opencode.jsonc`:
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>   "$schema": "https://opencode.ai/config.json",
>   "mcp": {
>     "localpayment": {
>       "type": "remote",
>       "url": "https://docs.localpayment.com/mcp",
>       "enabled": true
>     }
>   }
> }
> ```
>
> Em seguida, crie um arquivo `AGENTS.md` no seu projeto com o prompt do sistema:
>
> ```markdown theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> [PASTE THE SYSTEM PROMPT OF YOUR CHOSEN AGENT]
> ```
>
> O OpenCode aplicará as instruções do agente e chamará automaticamente as ferramentas MCP da Localpayment quando relevante.

> [tab] OpenHands
>
> O [OpenHands](https://github.com/All-Hands-AI/OpenHands) é uma plataforma de desenvolvimento de software com IA de código aberto e suporte nativo ao MCP.
>
> **Pela interface do OpenHands:**
>
> 1. Acesse **Settings → MCP** e adicione:
>    * **Transport**: Streamable HTTP
>    * **URL**: `https://docs.localpayment.com/mcp`
> 2. Inicie uma nova tarefa e cole o prompt do sistema do agente como instrução inicial.
>
> **Via `config.toml`:**
>
> ```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> [mcp]
> [[mcp.servers]]
> name = "localpayment"
> transport = "streamable_http"
> url = "https://docs.localpayment.com/mcp"
> ```

***

## Comparação de estruturas

| Estrutura | Linguagem | Tipo | MCP nativo | Licença | Ideal para |
| :- | :- | :- | :-: | :- | :- |
| **MCP (qualquer ferramenta)** | Qualquer | Ferramenta/IDE | ✔ | Varia | Desenvolvimento integrado ao IDE |
| **OpenAI Agents SDK** | Python | Estrutura | ✔ | MIT | Agentes autônomos simples |
| **LangChain** | Python / TS | Estrutura | ✔ | MIT | Cadeias e pipelines complexos |
| **Vercel AI SDK** | TypeScript | Estrutura | ✔ | Apache 2.0 | Aplicações Web e Next.js |
| **CrewAI** | Python | Estrutura | ✔ | MIT | Fluxos de trabalho multiagentes |
| **AgentScope** | Python | Estrutura | ✔ | Apache 2.0 | Sistemas multiagentes de produção |
| **Amazon Bedrock** | Python | Serviço em nuvem | ✔ (nativo) | Comercial | Implantações empresariais nativas da AWS |
| **OpenCode** | Qualquer | Agente terminal | ✔ | MIT | Agente de codificação de IA de terminal de código aberto |
| **OpenHands** | Qualquer | Plataforma | ✔ | MIT | Plataforma de agente de codificação de código aberto |

***

## Padrões e Ecossistema

Os agentes do Localpayment são construídos com base em padrões abertos. Compreender o ecossistema ajuda na extensão de agentes ou na criação de fluxos de trabalho com múltiplos agentes.

| Padrão | O que é isso? | Relevância |
| :- | :- | :- |
| **[MCP](https://modelcontextprotocol.io)** | Protocolo de Contexto de Modelo — padrão aberto para conectividade de ferramentas de IA | Base para todos os agentes da Localpayment |
| **[Protocolo A2A](https://github.com/a2aproject/A2A)** | Agent2Agent — Protocolo aberto do Google/Linux Foundation para comunicação entre agentes via JSON-RPC | Permite fluxos de trabalho multiagente entre agentes da Localpayment e seus agentes internos |
| **[AGENTS.md](https://agents.md)** | Formato aberto para instruções de agentes de empacotamento (usado em mais de 60 mil projetos, Claude Code, Goose e outros) | Arquivo padrão para distribuir os prompts do sistema de agente Localpayment dentro do seu projeto |
| **[Open Agent Format (OAF)](https://openagentformat.com)** | Formato de distribuição baseado em ZIP para agentes portáteis em múltiplas plataformas de IA | Empacote e compartilhe os agentes do Localpayment com sua equipe |

***

## Fluxos de trabalho multiagentes

Os agentes da Localpayment trabalham em conjunto com os agentes do seu projeto já existentes. Um fluxo de trabalho típico combina seus agentes internos (que conhecem seu código-fonte e arquitetura) com os agentes especialistas da Localpayment (que conhecem a API da Localpayment via MCP):

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'fontFamily': 'sans-serif'}}}%%
sequenceDiagram
    autonumber
    participant Dev as Desenvolvedor
    participant Orch as Agente interno
    participant Int as Agente integrador
    participant QA as Agente de QA
    participant MCP as Servidor MCP

    Dev->>Orch: Criar módulo de PayIn para a Colômbia

    rect rgb(219, 234, 254)
        Note over Orch,MCP: Fase de integração
        activate Int
        Orch->>Int: Gerar módulo de PayIn (Colômbia, Bre-B)
        Int->>MCP: list-endpoints / get-endpoint / search+fetch
        MCP-->>Int: Schemas e documentação atualizados
        Int-->>Orch: Módulo gerado (autenticação + cliente da API + handler de webhook)
        deactivate Int
    end

    rect rgb(220, 252, 231)
        Note over Orch,MCP: Fase de validação
        activate QA
        Orch->>QA: Validar esta integração
        QA->>MCP: get-endpoint / search códigos de erro + guias de segurança
        MCP-->>QA: Schemas e documentação atualizados
        QA-->>Orch: PASS: autenticação, campos, HTTPS / WARN: retry / FAIL: idempotência
        deactivate QA
    end

    rect rgb(254, 243, 199)
        Note over Orch,Int: Ciclo de correção
        Orch->>Int: Corrigir os itens FAIL
        Int-->>Orch: Módulo atualizado
        Orch->>QA: Revalidar
        QA-->>Orch: Todas as verificações aprovadas
    end

    Orch-->>Dev: Módulo de integração completo e validado
```

**Exemplo de prompt para o seu agente orquestrador (Cursor / Claude Code):**

```
You are working on our Express.js payment service. Use the Localpayment 
Integrator Agent context (already in .cursor/rules) to:

1. Generate the complete Localpayment PayIn module for Colombia (Bre-B) 
   in src/services/payments/localpayment/, following our existing service 
   pattern from src/services/payments/stripe/

2. Once generated, apply the Localpayment QA Agent checklist to validate 
   the implementation. Report any FAIL or WARN items.

3. Fix any FAIL items found in the QA review.

Use the Localpayment MCP for all API spec details.
```

***

## Compartilhe e distribua seus agentes

Ao contrário dos servidores MCP (que possuem links diretos para instalação), os prompts do sistema do agente são distribuídos como arquivos. A abordagem recomendada depende da configuração da sua equipe:

**Para uso individual:**

Copie o prompt do sistema desta página e adicione-o ao arquivo de regras ou instruções da sua ferramenta. Não é necessária instalação.

**Para distribuição em equipe via git:**

A maneira mais confiável de compartilhar agentes com sua equipe é adicionar os arquivos de configuração do sistema ao repositório do projeto. Todos os membros da equipe recebem automaticamente a mesma configuração de agente ao clonar ou atualizar o repositório.

Para Claude Code — crie `.claude/agents/localpayment-integrator.md`:

```markdown theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
---
name: localpayment-integrator
description: Specialist agent for building Localpayment API integrations. Use for any Localpayment payment, virtual account, webhook, or error code question.
---

[PASTE THE LOCALPAYMENT INTEGRATOR AGENT SYSTEM PROMPT HERE]
```

Para Cursor — faça commit de `.cursor/rules` com o conteúdo do prompt do sistema. Todos os membros da equipe que trabalham nesse repositório recebem o agente automaticamente.

Para OpenCode — faça commit de `AGENTS.md` com o prompt do sistema. O OpenCode o carrega em cada sessão.

**Seguindo o padrão aberto AGENTS.md:**

O [formato AGENTS.md](https://agents.md) é reconhecido pelo Claude Code, Goose e outras plataformas de agentes. Ele usa YAML como cabeçalho para metadados e Markdown para instruções — a mesma estrutura dos prompts do sistema acima.

***

## Sessão de exemplo

**Desenvolvedor:** Preciso validar minha integração com o CVU da Argentina antes de entrar em produção.

**Agente de QA Localpayment:** *(chama `get-endpoint POST /api/virtual-account` → lê o esquema em tempo real)*
*(chama `search("receive payment notifications")` → busca o guia de webhooks)*

**Componente analisado**: `POST /api/virtual-account` (CVU da Argentina)
**Versão da especificação consultada**: Esquema em tempo real via MCP `get-endpoint`

✅ APROVADO

* `externalId` é o formato UUID
* Todos os campos obrigatórios presentes: `country`, `accountNumber`, `beneficiary.type`, `beneficiary.name`

⚠️ ALERTA

* `beneficiary.document` é opcional para empresas locais na Argentina, mas recomendado para fins de conciliação.

❌ REPROVADO

* O manipulador de webhook não verifica `internalId` para processamento duplicado — adicione uma verificação de idempotência antes de creditar o pagamento.

**Resumo**: A integração está 85% concluída. Corrija a verificação de idempotência antes de implantar em produção.

***

> [card] [Biblioteca de prompts](https://docs.localpayment.com/pt-br/docs/prompt-library.md)
>
> Instruções prontas para usar, para tirar o máximo proveito de qualquer agente Localpayment.

> [card] [Segurança de IA](https://docs.localpayment.com/pt-br/docs/ai-security.md)
>
> Melhores práticas para usar ferramentas de IA com segurança em um contexto de integração fintech.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.