# Executar o runtime do Copilot em processo A hospedagem em processo carrega o runtime de Copilot nativo em seu processo de aplicativo em vez de iniciar um processo separado da CLI Copilot. Use-o para remover o gerenciamento de processos filhos, mantendo as mesmas sessões, eventos, ferramentas, hooks e comportamento JSON-RPC do SDK do Copilot. > \[!WARNING] > A hospedagem em processo é experimental em cada SDK. Teste o comportamento de inicialização, as transições do modelo e o comportamento de desligamento em todos os sistemas operacionais e arquiteturas nos quais você implanta. ## Quando usar a hospedagem em processo A hospedagem em processo é uma boa opção quando: * Seu aplicativo deve ser executado sem um processo de runtime separado. * Você quer que o SDK gerencie o ciclo de vida do runtime. * Você pode enviar uma biblioteca nativa para cada plataforma de implantação. * As configurações de ambiente e de diretório de trabalho de todo o processo são aceitáveis. Use [Configuração padrão (CLI empacotada)](/pt/copilot/how-tos/copilot-sdk/setup/bundled-cli) quando o isolamento do processo e o caminho de implantação mais estabelecido forem mais importantes. Use um [Configuração de serviços de back-end](/pt/copilot/how-tos/copilot-sdk/setup/backend-services) quando várias instâncias de aplicativo precisarem se conectar a um runtime compartilhado via TCP. ## Como funciona O SDK carrega a biblioteca nativa do runtime do Copilot e faz a vinculação com sua ABI C fixa. Todos os métodos do SDK continuam usando o protocolo JSON-RPC existente, delimitado por `Content-Length`, por uma conexão em memória. ![Diagrama: Fluxograma mostrando o processo descrito.](/assets/images/help/copilot/copilot-sdk/setup-in-process-runtime-diagram-0.png) O tempo de execução: * É executado no processo de aplicativo sem Node.js, um processo filho, uma porta TCP ou um token de conexão. * Oferece suporte às mesmas sessões, eventos de streaming, ferramentas, ganchos, permissões e solicitações do servidor para o cliente, assim como outros transportes. * Pode invocar callbacks do SDK a partir de threads de trabalho nativas. O SDK gerencia o encaminhamento entre threads e o ciclo de vida dos callbacks. * Mantém a biblioteca nativa carregada e seu pool de trabalho disponíveis durante o tempo de vida do processo de aplicativo. ## Requisitos do SDK Todos os SDKs expõem uma opção de conexão explícita em processo. Algumas linguagens exigem configuração adicional de compilação ou de pacote. | SDK | Opção de conexão | Requisito adicional | | ---------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | TypeScript | `RuntimeConnection.forInProcess()` | Nenhum quando o pacote inclui um pacote de runtime compatível | | Python | `RuntimeConnection.for_inprocess()` | Baixe previamente com `python -m copilot download-runtime --in-process` quando o download do runtime não estiver disponível durante a inicialização | | Go | `copilot.InProcessConnection{}` | Criar com `-tags copilot_inprocess` | | .NET | `RuntimeConnection.ForInProcess()` | Permitir o diagnóstico da `GHCP001` API experimental | | Rust | `Transport::InProcess` | Habilite o recurso `bundled-in-process` Cargo | | Java | `RuntimeConnection.forInProcess()` | Adicionar JNA, um classificador de runtime da plataforma, e a adesão à API experimental | O pacote de runtime nativo deve corresponder ao sistema operacional host, à arquitetura da CPU e à biblioteca C do Linux. Os hosts sem suporte falham durante a resolução ou inicialização em tempo de execução, em vez de retornar a um processo filho. ## Configurar uma conexão em processo Passe a opção de conexão específica do idioma ao criar o cliente.
TypeScript
```typescript import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk"; const client = new CopilotClient({ connection: RuntimeConnection.forInProcess(), }); await client.start(); ```
Python
```python from copilot import CopilotClient, RuntimeConnection client = CopilotClient( connection=RuntimeConnection.for_inprocess(), ) await client.start() ```
Go
```golang client := copilot.NewClient(&copilot.ClientOptions{ Connection: copilot.InProcessConnection{}, }) if err := client.Start(context.Background()); err != nil { log.Fatal(err) } defer client.Stop() ```
.NET
```csharp #pragma warning disable GHCP001 var client = new CopilotClient(new CopilotClientOptions { Connection = RuntimeConnection.ForInProcess(), }); await client.StartAsync(); ```
Rust
```rust let options = ClientOptions::default() .with_transport(Transport::InProcess); let client = Client::start(options).await?; ```
Java
```java import com.github.copilot.AllowCopilotExperimental; @AllowCopilotExperimental public class Example { public void run() throws Exception { CopilotClientOptions options = new CopilotClientOptions() .setConnection(RuntimeConnection.forInProcess()); CopilotClient client = new CopilotClient(options); client.start().join(); } } ``` `RuntimeConnection.forInProcess()` é `@CopilotExperimental`, portanto, a classe ou método de consumo deve aceitar `@AllowCopilotExperimental` (ou compilar com `-Acopilot.experimental.allowed=true`). Consulte [Usando APIs experimentais](https://github.com/github/copilot-sdk/tree/main/java/README.md#using-experimental-apis).
Você também pode definir `COPILOT_SDK_DEFAULT_CONNECTION=inprocess` antes de iniciar o aplicativo. O SDK usa esse valor somente quando o cliente não especifica uma conexão explicitamente. Um valor inválido faz com que a inicialização falhe. Prefira a configuração explícita do cliente no código do aplicativo. Use a variável de ambiente quando a configuração de implantação deve selecionar o transporte sem alterar o aplicativo. ## Configurar o tempo de execução O SDK converte opções tipadas de cliente compatíveis em argumentos nativos de runtime e valores de ambiente no escopo do host. Dependendo do SDK, essas opções incluem: * Token de autenticação e fallback de usuário conectado. * Diretório base do Copilot. * Nível de log. * Tempo limite de ociosidade da sessão. * Modo de sessão remota. O runtime em processo recebe um instantâneo do ambiente do host, além de substituições gerenciadas pelo SDK com suporte. Ele não modifica o ambiente do host. Defina valores em todo o processo antes de criar o primeiro cliente em processo. Isso inclui variáveis de ambiente que não são representadas por opções de cliente tipadas e pelo diretório de trabalho atual do aplicativo. ## Resolução da biblioteca em tempo de execução Cada SDK procura primeiro uma biblioteca de runtime empacotada ou armazenada em cache compatível. Você pode configurar `COPILOT_CLI_PATH` para apontar para um pacote de runtime compatível do Copilot quando precisar fornecer o runtime separadamente. Normalmente, apenas um caminho e uma versão da biblioteca nativa de tempo de execução podem ser carregados em um processo. Há suporte para iniciar outro cliente com a mesma biblioteca carregada, mas a tentativa de carregar uma biblioteca de runtime diferente falha. Para implantações de produção: 1. Crie e teste o aplicativo para cada plataforma de destino. 2. Verifique se o artefato de runtime nativo correspondente está incluído no pacote implantado ou disponível por meio do mecanismo de download de runtime do SDK. 3. Inicie pelo menos uma sessão e conclua uma curva de modelo em um teste de fumaça de implantação. 4. Interrompa os clientes normalmente antes que o aplicativo seja encerrado. ## Comportamento do ciclo de vida Iniciar um cliente em processo carrega a biblioteca nativa, cria um host de runtime, abre uma conexão na memória e executa o handshake normal de versão de protocolo do SDK. Durante o desligamento normal, o SDK: 1. Fecha sessões ativas. 2. Solicita o desligamento normal do ambiente de execução via JSON-RPC. 3. Fecha o JSON-RPC e as conexões nativas. 4. Libera o host de tempo de execução. A biblioteca nativa pode permanecer carregada até que o processo do aplicativo seja encerrado. Não conte com descarregar e substituir a biblioteca de tempo de execução após o primeiro uso. ## Limitations A hospedagem em processo tem estas restrições atuais: * **API experimental**: os requisitos de comportamento e empacotamento podem ser alterados entre versões. * **Estado do processo compartilhado**: todos os clientes compartilham o ambiente do processo de host, o diretório de trabalho atual, a biblioteca nativa e o pool de trabalho de runtime. * **Opções de processo restrito**: as opções do SDK para um ambiente arbitrário, diretório de trabalho, configuração de telemetria, caminho executável ou argumentos da CLI são rejeitadas quando aplicável. Configure valores globais do processo no processo hospedeiro e use opções tipadas compatíveis para configurações de tempo de execução. * **Nenhum diretório de trabalho por cliente**: o runtime usa o diretório de trabalho do processo de hospedagem. * **Uma versão de runtime por processo**: não há suporte para carregar outro caminho ou versão de biblioteca nativa. * **A maturidade da plataforma varia**: algumas combinações de SDK e plataforma reduziram a cobertura de desligamento ou de turno de modelo. Valide a combinação exata que você implanta. ## Leitura adicional * [Guias de configuração](/pt/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path): comparar a hospedagem em processo com outros modelos de implantação * [Configuração padrão (CLI empacotada)](/pt/copilot/how-tos/copilot-sdk/setup/bundled-cli): execute o runtime empacotado em um processo filho gerenciado * [Configuração de serviços de back-end](/pt/copilot/how-tos/copilot-sdk/setup/backend-services): conectar aplicativos a um runtime compartilhado via TCP * [Ganchos de ciclo de vida de sessão](/pt/copilot/how-tos/copilot-sdk/hooks/session-lifecycle): manipular eventos de início e término da sessão