Usando a entrada de imagem com o SDK do Copilot

Observação

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Há duas maneiras de anexar imagens a uma SDK do Copilot sessão:

        **Anexo** de arquivo (`type: "file"`)— forneça um caminho absoluto; o runtime lê o arquivo do disco, converte-o em base64 e envia-o para o LLM.

        **Blob Attachment** (`type: "blob"`)— forneça diretamente os dados codificados em base64; útil quando a imagem já estiver na memória (por exemplo, capturas de tela, imagens geradas ou dados de uma API).

Para obter um diagrama de sequência do fluxo de entrada da imagem, consulte o github/copilot-sdk repositório.

Conceito	Descrição

          **Anexo de arquivo** | Um anexo com `type: "file"` e um absoluto `path` a uma imagem em disco |

| Anexo Blob | Um anexo com type: "blob", codificado em base64 data e mimeType—sem necessidade de E/S de disco | | Codificação automática | Para anexos de arquivo, o runtime lê a imagem e a converte em base64 automaticamente | | Redimensionamento automático | O runtime redimensiona ou reduz automaticamente as imagens que excedem os limites específicos do modelo | | Capacidade de visão | O modelo deve capabilities.supports.vision = true para processar imagens |

Início rápido: anexo de arquivo

Anexe um arquivo de imagem a qualquer mensagem usando o tipo de anexo de arquivo. O caminho deve ser um caminho absoluto para uma imagem no disco.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

await session.send({
    prompt: "Describe what you see in this image",
    attachments: [
        {
            type: "file",
            path: "/absolute/path/to/screenshot.png",
        },
    ],
});

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Início rápido: anexo de blob

Quando você já tiver dados de imagem na memória (por exemplo, uma captura de tela capturada pelo aplicativo ou uma imagem buscada de uma API), use um anexo de blob para enviá-los diretamente sem gravar em disco.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

const base64ImageData = "..."; // your base64-encoded image
await session.send({
    prompt: "Describe what you see in this image",
    attachments: [
        {
            type: "blob",
            data: base64ImageData,
            mimeType: "image/png",
            displayName: "screenshot.png",
        },
    ],
});

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Formatos com suporte

Os formatos de imagem com suporte incluem JPG, PNG, GIF e outros tipos de imagem comuns. Para anexos de arquivo, o runtime lê a imagem do disco e a converte conforme necessário. Para anexos de blob, você fornece os dados base64 e o tipo MIME diretamente. Use PNG ou JPEG para obter melhores resultados, pois esses são os formatos mais amplamente compatíveis.

O campo do modelo capabilities.limits.vision.supported_media_types lista os tipos MIME exatos que ele aceita.

Processamento automático

O runtime processa automaticamente as imagens para se ajustarem às restrições do modelo. Nenhum redimensionamento manual é necessário.

As imagens que excedem a dimensão ou os limites de tamanho do modelo são redimensionadas automaticamente (preservando a proporção de aspecto) ou têm a qualidade reduzida.
Se uma imagem não puder ser trazida dentro dos limites após o processamento, ela será ignorada e não será enviada para a LLM.
O campo do modelo indica o tamanho máximo da capabilities.limits.vision.max_prompt_image_size imagem em bytes.

Funcionalidades do modelo de visão

Nem todos os modelos dão suporte à visão. Verifique os recursos do modelo antes de enviar imagens.

Campos de funcionalidade

Campo	Tipo	Descrição
`capabilities.supports.vision`	`boolean`	Se o modelo pode processar entradas de imagem
`capabilities.limits.vision.supported_media_types`	`string[]`	tipos MIME que o modelo aceita (por exemplo, `["image/png", "image/jpeg"]`)
`capabilities.limits.vision.max_prompt_images`	`number`	Número máximo de imagens por prompt
`capabilities.limits.vision.max_prompt_image_size`	`number`	Tamanho máximo da imagem em bytes

Tipo de limites de visão

vision?: {
    supported_media_types: string[];
    max_prompt_images: number;
    max_prompt_image_size: number; // bytes
};

Recebendo resultados de imagem

Quando as ferramentas retornam imagens (por exemplo, capturas de tela ou gráficos gerados), o resultado contém "image" blocos de conteúdo com dados codificados em base64.

Campo	Tipo	Descrição
`type`	`"image"`	Tipo de bloco de conteúdo discriminatório
`data`	`string`	Dados de imagem codificados em Base64
`mimeType`	`string`	Tipo MIME (por exemplo, `"image/png"`)

Os blocos de imagem aparecem nos resultados do evento tool.execution_complete. Para obter mais informações, consulte Eventos de streaming no SDK do Copilot.

Dicas e limitações

Dica	Detalhes

          **Usar PNG ou JPEG** | Evita sobrecarga de conversão: eles são enviados para o LLM como estão. |

| Manter as imagens razoavelmente dimensionadas | Imagens grandes podem ter a qualidade reduzida, o que pode resultar na perda de detalhes importantes. | | Usar caminhos absolutos para anexos de arquivo | O runtime lê arquivos do disco; caminhos relativos podem não ser resolvidos corretamente | | Use anexos de blobs para dados em memória | Quando você já tem dados base64 (por exemplo, capturas de tela, respostas de API), o blob evita E/S de disco desnecessário | | Verificar o suporte à visão primeiro | Enviar imagens para um modelo sem visão desperdiça tokens, pois não há compreensão visual. | | Há suporte para várias imagens | Anexar vários anexos em uma mensagem, até o limite do max_prompt_images modelo | | Não há suporte para SVG | Os arquivos SVG são baseados em texto e excluídos do processamento de imagem |

Leitura adicional

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events) — ciclo de vida do evento, incluindo blocos de conteúdo de resultado da ferramenta

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/steering-and-queueing) – enviando mensagens de acompanhamento com anexos