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

# Aplicativos de referência

> Execute dois aplicativos completos em Python criados com a API MKA1: triagem de tickets e analista de CSV.

Dois aplicativos de referência executáveis mostram o que você pode criar com a API MKA1. Cada um é um pequeno aplicativo web em Python com uma interface de navegador, dados de exemplo fictícios e testes próprios. O código-fonte está no repositório público [mka1-reference-apps](https://github.com/MeetKai/mka1-reference-apps), sob a licença Apache 2.0.

| Aplicativo | O que faz | Recursos da MKA1 |
| - | - | - |
| [Triagem de tickets](#triagem-de-tickets) | Transforma um ticket de suporte ao cliente em uma equipe, uma prioridade, uma justificativa e uma próxima ação sugeridas | Responses com saída estruturada |
| [Analista de CSV](#analista-de-csv) | Analisa um CSV enviado em um sandbox e retorna um relatório HTML | Responses com a ferramenta `shell`, e sessões e arquivos de sandbox |

Os dois aplicativos usam o SDK Python da MKA1. Cada diretório de aplicativo é independente, então você pode copiá-lo para o seu próprio repositório.

## Antes de começar

Você precisa de:

* Python 3.12 ou posterior e [uv](https://docs.astral.sh/uv/getting-started/installation/).
* Uma [chave de API](https://docs.mka1.com/pt/docs/authentication.md) da MKA1 e um [modelo](https://docs.mka1.com/docs/models.md) habilitado na sua organização.
* Para o analista de CSV, capacidade de sandbox no seu cluster.

Clone o repositório:

```bash theme={null}
git clone https://github.com/MeetKai/mka1-reference-apps.git
cd mka1-reference-apps
```

Os aplicativos chamam a API real, então as solicitações deles usam os modelos da sua organização e, no caso do analista de CSV, os recursos de sandbox dela. A chave de API fica no servidor Python; o navegador nunca a recebe. Cada solicitação usa uma nova identidade de usuário final de demonstração em `X-On-Behalf-Of`, e cada solicitação de Responses define `store` como `false`.

## Triagem de tickets

Código-fonte: [`apps/ticket-triage`](https://github.com/MeetKai/mka1-reference-apps/tree/main/apps/ticket-triage)

Cole um ticket de suporte de telecomunicações ou escolha um exemplo fictício. O aplicativo sugere uma equipe (cobrança, suporte técnico ou serviços de conta), uma prioridade de P1 a P3, um resumo, uma justificativa e uma próxima ação para revisão humana. Ele não envia tickets, não altera contas nem envia mensagens.

O aplicativo demonstra:

* Uma solicitação de Responses com instruções de roteamento e um esquema JSON estrito em `text.format`, para que o modelo retorne uma decisão estruturada.
* A validação dessa decisão antes de exibi-la. O aplicativo rejeita respostas incompletas, recusas do modelo, JSON inválido, valores desconhecidos de equipe ou prioridade e campos extras.

Ele precisa de um modelo que suporte saída estruturada. A configuração de exemplo usa `openai:gpt-4.1-mini`; a disponibilidade depende da sua organização.

Para executá-lo, instale as dependências e crie o arquivo de configuração:

```bash theme={null}
cd apps/ticket-triage
uv sync --locked
cp .env.example .env
```

Edite `.env`. Defina `MKA1_API_KEY` com a sua chave de API, `MKA1_SERVER_URL` com a URL do gateway do seu cluster e `MKA1_MODEL` com um modelo habilitado que suporte saída estruturada. Depois, inicie o aplicativo:

```bash theme={null}
uv run uvicorn app:app --host 127.0.0.1 --port 8001
```

Abra `http://127.0.0.1:8001`, escolha **Business connectivity outage** e envie o ticket. O resultado esperado é `technical_support` e `P1`. O texto pode variar entre execuções do modelo.

## Analista de CSV

Código-fonte: [`apps/csv-analyst`](https://github.com/MeetKai/mka1-reference-apps/tree/main/apps/csv-analyst)

Envie um CSV, faça uma pergunta e baixe um relatório HTML com resultados calculados, tabelas, métodos e limitações. Cada análise é executada no próprio sandbox.

O aplicativo demonstra:

* O ciclo de vida de uma sessão de sandbox: cria uma sessão com o recurso Python e duração de dez minutos, envia o CSV, baixa o relatório e encerra a sessão quando a análise termina, inclusive após uma falha.
* Uma solicitação de Responses com uma ferramenta `shell` vinculada a essa sessão. O modelo usa Python no sandbox para analisar o arquivo e escrever o relatório.
* A validação e a sanitização do relatório gerado antes que o navegador o receba.

Ele precisa de um modelo que possa usar ferramentas de shell e de capacidade de sandbox no seu cluster. A configuração de exemplo usa `openai:gpt-4.1`; a disponibilidade depende da sua organização.

Para executá-lo, instale as dependências e crie o arquivo de configuração:

```bash theme={null}
cd apps/csv-analyst
uv sync --locked
cp .env.example .env
```

Edite `.env` com a sua chave de API, a URL do gateway e o modelo, usando as mesmas variáveis da triagem de tickets. Depois, inicie o aplicativo:

```bash theme={null}
uv run uvicorn app:app --host 127.0.0.1 --port 8002
```

Abra `http://127.0.0.1:8002`, clique em **Use example data**, mantenha a pergunta padrão e clique em **Generate report**. Baixe o relatório quando ele terminar. Nos dados de exemplo, a receita mensal total é de $61,000 em julho, $64,950 em agosto e \$69,000 em setembro; use esses valores para verificar o relatório.

O aplicativo aceita um CSV de até 1 MB, 20.000 linhas de dados e 50 colunas, e executa uma análise por vez em cada processo do servidor. Revise cada relatório antes de confiar nele: uma resposta concluída não prova que todos os cálculos estão corretos.

## Antes de hospedar um aplicativo para outros usuários

Os dois aplicativos foram feitos para execução local: eles se vinculam a localhost e rejeitam envios do navegador de outras origens. Antes de hospedar um deles para outros usuários:

* Adicione autenticação ao aplicativo e associe os usuários autenticados a identidades de usuário final autorizadas.
* Aplique cotas por usuário.
* Configure o seu proxy reverso e os hosts permitidos.
* Mantenha as chaves de API no servidor.
* No analista de CSV, aplique as restrições de rede e de sistema de arquivos necessárias por meio da sua infraestrutura de sandbox. Instruções do modelo não são um limite de isolamento.

## Guias relacionados

* [Gerar uma resposta](https://docs.mka1.com/pt/docs/generate-a-response.md)
* [Execução de código](https://docs.mka1.com/docs/code-execution.md)
* [Sandbox](https://docs.mka1.com/docs/sandbox.md)


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