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

# Quickstart

> Comece a usar o Ponte SDK em minutos e execute seu primeiro agente AI com Model Context Protocol.

## Obtenha sua Chave de API

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

<Steps>
  <Step title="Crie sua conta">
    Acesse [ponte.ai](https://ponte.ai) e crie uma conta gratuita. Você receberá **\$5 em créditos** para começar.
  </Step>

  <Step title="Acesse o Dashboard">
    Faça login e navegue até a seção **API Keys** no menu lateral.
  </Step>

  <Step title="Gere sua chave">
    Clique em **"Criar Nova API Key"**, dê um nome descritivo (ex: "Desenvolvimento Local") e copie a chave gerada.
  </Step>

  <Step title="Configure no ambiente">
    Adicione sua chave ao arquivo `.env` do seu projeto:

    ```bash .env theme={"theme":"one-dark-pro"}
    PONTE_API_KEY=ponte_live_abc123xyz...
    ```
  </Step>
</Steps>

<Warning>
  **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`.
</Warning>

## Instalação

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

<CodeGroup>
  ```bash npm theme={"theme":"one-dark-pro"}
  npm install @ponte/sdk
  ```

  ```bash yarn theme={"theme":"one-dark-pro"}
  yarn add @ponte/sdk
  ```

  ```bash pnpm theme={"theme":"one-dark-pro"}
  pnpm add @ponte/sdk
  ```

  ```bash bun theme={"theme":"one-dark-pro"}
  bun add @ponte/sdk
  ```
</CodeGroup>

## Seu Primeiro Agente

Vamos criar seu primeiro agente AI em 3 minutos:

<CodeGroup>
  ```typescript index.ts theme={"theme":"one-dark-pro"}
  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();
  ```

  ```javascript index.js theme={"theme":"one-dark-pro"}
  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();
  ```
</CodeGroup>

Execute o código:

```bash theme={"theme":"one-dark-pro"}
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
```

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

## Usando MCP Servers

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

<CodeGroup>
  ```typescript Busca Web theme={"theme":"one-dark-pro"}
  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();
  ```

  ```typescript Integração Pagamento theme={"theme":"one-dark-pro"}
  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();
  ```

  ```typescript Sistema de Arquivos theme={"theme":"one-dark-pro"}
  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();
  ```
</CodeGroup>

<Info>
  **Descubra mais MCP Servers** no [Marketplace](https://ponte.ai/marketplace). Existem servidores para GitHub, Slack, Google Drive, bases de dados e muito mais!
</Info>

## Agentes com Memória

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

<Tabs>
  <Tab title="Conversation (Recomendado)">
    Use a classe `Conversation` para gerenciar histórico facilmente:

    ```typescript theme={"theme":"one-dark-pro"}
    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
  </Tab>

  <Tab title="Array de Messages">
    Use array direto para controle total:

    ```typescript theme={"theme":"one-dark-pro"}
    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
  </Tab>

  <Tab title="Conversão Híbrida">
    Converta entre as duas abordagens conforme necessário:

    ```typescript theme={"theme":"one-dark-pro"}
    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
  </Tab>
</Tabs>

<Info>
  **Saiba mais:** Veja o [Guia de Memória](/docs/memory) para casos de uso avançados como fork, branching e RAG.
</Info>

## 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       |

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

## Tratamento de Erros

Sempre implemente tratamento de erros robusto:

```typescript theme={"theme":"one-dark-pro"}
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  |

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

## Configuração Avançada

Customize o cliente Ponte para suas necessidades:

```typescript theme={"theme":"one-dark-pro"}
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:

<CardGroup cols={2}>
  <Card title="Guia de Memória" icon="messages" href="/docs/memory">
    Aprenda sobre fork, branching, RAG e casos de uso avançados
  </Card>

  <Card title="MCP Marketplace" icon="store" href="/marketplace">
    Descubra servidores MCP para GitHub, Slack, pagamentos e mais
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api">
    Documentação completa de todas as funcionalidades do SDK
  </Card>

  <Card title="Exemplos Práticos" icon="lightbulb" href="/docs/examples">
    Veja exemplos reais de agentes e automações
  </Card>
</CardGroup>

## Precisa de Ajuda?

<AccordionGroup>
  <Accordion title="Como eu sei quantos créditos gastei?">
    Acesse o [Dashboard de Billing](https://ponte.ai/billing) para ver seu uso em tempo real. Você também pode verificar `tokensUsed` em cada resposta da API.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/pricing).
  </Accordion>

  <Accordion title="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](/docs/mcp-servers).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Card title="Ainda com dúvidas?" icon="discord" href="https://discord.gg/ponte">
  Junte-se à nossa comunidade no Discord para suporte da equipe e outros desenvolvedores
</Card>