Quickstart

Obtenha sua Chave de API

Para usar o Ponte, você precisará de uma chave de API. Siga estes passos:

Crie sua conta

Acesse ponte.ai e crie uma conta gratuita. Você receberá $5 em créditos para começar.

Acesse o Dashboard

Faça login e navegue até a seção API Keys no menu lateral.

Gere sua chave

Clique em “Criar Nova API Key”, dê um nome descritivo (ex: “Desenvolvimento Local”) e copie a chave gerada.

Configure no ambiente

Adicione sua chave ao arquivo .env do seu projeto:

.env

PONTE_API_KEY=ponte_live_abc123xyz...

Mantenha sua chave segura! Nunca compartilhe sua API key publicamente ou commit ela no git. Use variáveis de ambiente e adicione .env ao seu .gitignore.

Instalação

Instale o SDK do Ponte usando seu gerenciador de pacotes preferido:

npm install @ponte/sdk

yarn add @ponte/sdk

pnpm add @ponte/sdk

bun add @ponte/sdk

Seu Primeiro Agente

Vamos criar seu primeiro agente AI em 3 minutos:

import { Ponte } from '@ponte/sdk';

// Inicializa o cliente
const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function main() {
  try {
    // Executa uma pergunta simples
    const resultado = await ponte.execute({
      input: 'Explique o que é o Model Context Protocol em 2 frases.',
      model: 'claude-3-5-haiku-latest'
    });
    
    console.log('🤖 Texto gerado:', resultado.text);
    console.log('⚡ Latência:', resultado.latency, 'ms');
    console.log('📊 Tokens:', resultado.tokensUsed);
  } catch (error) {
    console.error('❌ Erro:', error);
  }
}

main();

const { Ponte } = require('@ponte/sdk');

// Inicializa o cliente
const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY
});

async function main() {
  try {
    // Executa uma pergunta simples
    const resultado = await ponte.execute({
      input: 'Explique o que é o Model Context Protocol em 2 frases.',
      model: 'claude-3-5-haiku-latest'
    });
    
    console.log('🤖 Texto gerado:', resultado.text);
    console.log('⚡ Latência:', resultado.latency, 'ms');
    console.log('📊 Tokens:', resultado.tokensUsed);
  } catch (error) {
    console.error('❌ Erro:', error);
  }
}

main();

Execute o código:

node index.js
# ou
bun run index.ts

Resultado esperado:

🤖 Texto gerado: O Model Context Protocol (MCP) é um padrão aberto que permite...
⚡ Latência: 423 ms
📊 Tokens: 127

Funcionou? Parabéns! Você acabou de executar seu primeiro agente AI com o Ponte. 🎉

Usando MCP Servers

A verdadeira mágica do Ponte está nos MCP Servers - ferramentas que dão superpoderes aos seus agentes:

import { Ponte } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function buscaWeb() {
  const resultado = await ponte.execute({
    input: 'Busque notícias sobre IA das últimas 24 horas e resuma os 3 principais destaques.',
    model: 'gpt-4o-mini',
    mcpServers: ['@modelcontextprotocol/server-brave-search']
  });
  
  console.log('📰 Notícias:', resultado.text);
  console.log('🛠️ Ferramentas usadas:', resultado.toolsUsed);
}

buscaWeb();

import { Ponte } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function criarCliente() {
  const resultado = await ponte.execute({
    input: `Crie um cliente na Abacate Pay com os dados:
      - Nome: Maria Silva
      - Email: maria.silva@empresa.com.br
      - CPF: 123.456.789-00
      - Telefone: (11) 98765-4321`,
    model: 'gpt-4o-mini',
    mcpServers: ['@abacatepay']
  });
  
  console.log('✅ Cliente criado:', resultado.text);
}

criarCliente();

import { Ponte } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function analisarArquivos() {
  const resultado = await ponte.execute({
    input: 'Liste todos os arquivos .ts no diretório src/ e me diga qual é o maior arquivo.',
    model: 'claude-3-5-sonnet-latest',
    mcpServers: ['@modelcontextprotocol/server-filesystem']
  });
  
  console.log('📁 Análise:', resultado.text);
}

analisarArquivos();

Descubra mais MCP Servers no Marketplace. Existem servidores para GitHub, Slack, Google Drive, bases de dados e muito mais!

Agentes com Memória

Para criar agentes inteligentes que mantêm contexto entre interações, você tem duas opções:

Conversation (Recomendado)
Array de Messages
Conversão Híbrida

Use a classe Conversation para gerenciar histórico facilmente:

import { Ponte, Conversation } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function exemploMemoria() {
  // Cria agente com personalidade definida
  const conversation = new Conversation(
    'Você é um assistente técnico especializado em JavaScript e TypeScript.'
  );

  // Primeira interação
  conversation.addUserMessage('O que é uma Promise?');
  
  let resultado = await ponte.execute({
    conversation, // ✅ Passa o objeto direto
    model: 'claude-3-5-haiku-latest'
  });

  conversation.addAssistantMessage(resultado.text);
  console.log('🤖 Explicação 1:', resultado.text);

  // Segunda interação (com contexto da primeira)
  conversation.addUserMessage('E async/await?');
  
  resultado = await ponte.execute({
    conversation, // Contexto automático!
    model: 'claude-3-5-haiku-latest'
  });

  console.log('🤖 Explicação 2:', resultado.text);
  
  // Métodos úteis
  console.log('📊 Total mensagens:', conversation.length());
  console.log('💭 Tokens estimados:', conversation.estimateTokens());
}

exemploMemoria();

Por que usar Conversation?

✅ Código mais limpo e legível
✅ Previne erros comuns (ordem de mensagens, duplicação)
✅ Métodos úteis (fork, estimateTokens, clear, etc)
✅ Perfeito para iniciantes

Use array direto para controle total:

import { Ponte, type Message } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function exemploArray() {
  // Array tradicional (compatível com OpenAI/Anthropic)
  const messages: Message[] = [
    { 
      role: 'system', 
      content: 'Você é um assistente técnico especializado em JavaScript.'
    },
    { 
      role: 'user', 
      content: 'O que é uma Promise?' 
    }
  ];

  let resultado = await ponte.execute({
    messages, // ✅ Passa array direto
    model: 'claude-3-5-haiku-latest'
  });

  // Adiciona resposta ao histórico
  messages.push({
    role: 'assistant',
    content: resultado.text
  });

  // Segunda pergunta
  messages.push({
    role: 'user',
    content: 'E async/await?'
  });

  resultado = await ponte.execute({
    messages,
    model: 'claude-3-5-haiku-latest'
  });

  console.log('🤖 Explicação:', resultado.text);
}

exemploArray();

Por que usar array?

✅ Total controle sobre o histórico
✅ Fácil de salvar/carregar do banco de dados
✅ Compatível com outros SDKs (OpenAI, Anthropic)
✅ Flexível para edição e branching

Converta entre as duas abordagens conforme necessário:

import { Ponte, Conversation, type Message } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function exemploHibrido() {
  // 1. Carrega conversa do banco (array)
  const messagesFromDB: Message[] = await loadFromDatabase('conv-123');

  // 2. Converte para Conversation (usar métodos úteis)
  const conversation = Conversation.fromMessages(messagesFromDB);

  // 3. Adiciona nova mensagem
  conversation.addUserMessage('Continue a conversa...');

  // 4. Executa
  const resultado = await ponte.execute({
    conversation,
    model: 'gpt-4o-mini'
  });

  conversation.addAssistantMessage(resultado.text);

  // 5. Converte de volta e salva
  const updatedMessages = conversation.toObject();
  await saveToDatabase('conv-123', updatedMessages);

  // Ou salva como JSON
  const json = conversation.toJSON();
  await saveToDatabase('conv-123', json);
}

// Helper functions
async function loadFromDatabase(id: string): Promise<Message[]> {
  const data = await db.conversations.findById(id);
  return JSON.parse(data.messages);
}

async function saveToDatabase(id: string, messages: Message[] | string) {
  const data = typeof messages === 'string' 
    ? messages 
    : JSON.stringify(messages);
  
  await db.conversations.update(id, { messages: data });
}

Por que usar conversão híbrida?

✅ Melhor dos dois mundos
✅ Array para banco, Conversation para lógica
✅ Flexibilidade máxima

Saiba mais: Veja o Guia de Memória para casos de uso avançados como fork, branching e RAG.

Modelos Disponíveis

Escolha o modelo ideal para seu caso de uso:

Modelo	Provider	Velocidade	Custo	Melhor para
claude-3-5-haiku-latest	Anthropic	⚡⚡⚡	$	Respostas rápidas, análise simples
gpt-4o-mini	OpenAI	⚡⚡⚡	$	Uso geral, ótimo custo-benefício
claude-3-5-sonnet-latest	Anthropic	⚡⚡	$$	Tarefas complexas, raciocínio
gpt-4o	OpenAI	⚡⚡	$$	Multimodal, visão + texto
claude-opus-4	Anthropic	⚡	$$$	Análises profundas, pesquisa

Dica de economia: Use Haiku ou GPT-4o-mini para 90% dos casos. Reserve modelos mais caros para tarefas que realmente precisam.

Tratamento de Erros

Sempre implemente tratamento de erros robusto:

import { Ponte, PonteError } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!
});

async function exemploComErros() {
  try {
    const resultado = await ponte.execute({
      input: 'Sua pergunta aqui',
      model: 'claude-3-5-haiku-latest',
      mcpServers: ['@servidor/exemplo']
    });
    
    console.log('✅ Sucesso:', resultado.text);
    
  } catch (error) {
    if (error instanceof PonteError) {
      // Erro da API Ponte
      console.error('❌ Erro Ponte:', {
        mensagem: error.message,
        codigo: error.code,
        status: error.statusCode,
        detalhes: error.details
      });
      
      // Tratamento específico por código
      switch (error.code) {
        case 'INSUFFICIENT_CREDITS':
          console.log('💳 Adicione créditos em https://ponte.ai/billing');
          break;
        case 'RATE_LIMIT_EXCEEDED':
          console.log('⏳ Aguarde alguns segundos e tente novamente');
          break;
        case 'INVALID_API_KEY':
          console.log('🔑 Verifique sua API key');
          break;
        default:
          console.log('🔄 Tente novamente');
      }
    } else {
      // Erro genérico
      console.error('❌ Erro inesperado:', error);
    }
  }
}

exemploComErros();

Códigos de Erro Comuns

Código	Descrição	Solução
`MISSING_API_KEY`	API key não fornecida	Configure `PONTE_API_KEY` no ambiente
`INVALID_API_KEY`	API key inválida ou expirada	Gere nova chave no dashboard
`INSUFFICIENT_CREDITS`	Créditos insuficientes	Adicione créditos em ponte.ai/billing
`RATE_LIMIT_EXCEEDED`	Muitas requisições	Aguarde ou faça upgrade do plano
`SERVER_NOT_FOUND`	MCP Server não existe	Verifique o nome no marketplace
`EXECUTION_TIMEOUT`	Execução excedeu tempo limite	Use modelo mais rápido ou simplifique prompt

Rate Limits

O Ponte possui limites de requisições por minuto baseados no seu plano:

Plano	Requisições/min	MCP Tool Calls/mês	Custo
Free	60	50 grátis, depois $0.005/call	$0/mês
Pro	300	1000 grátis, depois $0.0025/call	$20/mês
Enterprise	Customizado	Customizado	Contato

Se você exceder o rate limit, receberá um erro RATE_LIMIT_EXCEEDED. Aguarde alguns segundos e tente novamente, ou implemente retry com backoff exponencial.

Configuração Avançada

Customize o cliente Ponte para suas necessidades:

import { Ponte } from '@ponte/sdk';

const ponte = new Ponte({
  apiKey: process.env.PONTE_API_KEY!,
  
  // URL base (útil para ambiente de desenvolvimento)
  baseUrl: 'https://api.ponte.ai', // default
  
  // Timeout em milissegundos
  timeout: 60000, // default: 30000 (30s)
  
  // Retry automático em caso de erro
  retry: true, // default: true
  
  // Número máximo de tentativas
  maxRetries: 3 // default: 3
});

Próximos Passos

Agora que você tem o básico, explore mais recursos:

Guia de Memória

Aprenda sobre fork, branching, RAG e casos de uso avançados

MCP Marketplace

Descubra servidores MCP para GitHub, Slack, pagamentos e mais

API Reference

Documentação completa de todas as funcionalidades do SDK

Exemplos Práticos

Veja exemplos reais de agentes e automações

Precisa de Ajuda?

Como eu sei quantos créditos gastei?

Acesse o Dashboard de Billing para ver seu uso em tempo real. Você também pode verificar tokensUsed em cada resposta da API.

Posso usar o Ponte em produção?

Sim! O Ponte é production-ready com SLA de 99.9% para clientes Pro e Enterprise. Configure monitoring adequado e implemente retry logic.

Como funciona o pricing dos MCP Servers?

Cada MCP server tem um custo por tool call. Plano Free:

0.005/call (após 50 grátis). Plano Pro:

0.0025/call (após 1000 grátis). Veja detalhes em Pricing.

Posso criar meus próprios MCP Servers?

Sim! Você pode criar servidores customizados e hospedá-los no Ponte. Veja o Guia de Desenvolvimento de Servidores.

O SDK funciona em ambientes edge (Vercel, Cloudflare)?

Sim! O SDK é compatível com Vercel Edge Functions, Cloudflare Workers e outros runtimes edge. Use fetch nativo e não há dependências do Node.js.

Existe limite de tamanho de contexto?

O limite depende do modelo escolhido. Claude Sonnet suporta até 200K tokens, GPT-4o até 128K. Use conversation.estimateTokens() para monitorar.

Ainda com dúvidas?

Junte-se à nossa comunidade no Discord para suporte da equipe e outros desenvolvedores

Começando

Guias

Obtenha sua Chave de API

Instalação

Seu Primeiro Agente

Usando MCP Servers

Agentes com Memória

Modelos Disponíveis

Tratamento de Erros

Códigos de Erro Comuns

Rate Limits

Configuração Avançada

Próximos Passos

Guia de Memória

MCP Marketplace

API Reference

Exemplos Práticos

Precisa de Ajuda?

Ainda com dúvidas?

​Obtenha sua Chave de API

​Instalação

​Seu Primeiro Agente

​Usando MCP Servers

​Agentes com Memória

​Modelos Disponíveis

​Tratamento de Erros

​Códigos de Erro Comuns

​Rate Limits

​Configuração Avançada

​Próximos Passos

Guia de Memória

MCP Marketplace

API Reference

Exemplos Práticos

​Precisa de Ajuda?

Ainda com dúvidas?

Obtenha sua Chave de API

Instalação

Seu Primeiro Agente

Usando MCP Servers

Agentes com Memória

Modelos Disponíveis

Tratamento de Erros

Códigos de Erro Comuns

Rate Limits

Configuração Avançada

Próximos Passos

Precisa de Ajuda?