SDK do Cortex Code Agent¶

Pré-requisitos¶

1. Instale a Cortex Code CLI¶

Instalar a CLI:

curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | sh

2. Instale o SDK¶

Instalar o SDK do npm ou PyPI:

npm install cortex-code-agent-sdk

pip install cortex-code-agent-sdk

3. Configure a conexão com o Snowflake¶

O SDK faz a autenticação usando as configurações de conexão na SnowflakeCLI. Adicione uma conexão a ~/.snowflake/connections.toml ou use uma configuração existente em ~/.snowflake/config.toml (consulte Configurando as conexões):

[my-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "externalbrowser"

O SDK usa a conexão padrão da CLI, a menos que você especifique uma explicitamente por meio da opção connection.

Se a Cortex CodeCLI não está em seu PATH, aponte o SDK para ele definindo CORTEX_CODE_CLI_PATH=/path/to/cortex ou passando cliPath (TypeScript) ou cli_path (Python) nas opções do SDK.

4. Execute seu primeiro agente¶

O exemplo a seguir cria um agente que explora seu projeto e resume o que ele faz:

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "What does this codebase do? Give me a one-paragraph summary.",
  options: { cwd: process.cwd() },
})) {
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
  if (message.type === "result") {
    console.log("\nDone:", message.subtype);
  }
}

import asyncio
from cortex_code_agent_sdk import query, AssistantMessage, ResultMessage, CortexCodeAgentOptions

async def main():
    async for message in query(
        prompt="What does this codebase do? Give me a one-paragraph summary.",
        options=CortexCodeAgentOptions(cwd="."),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text, end="")
        elif isinstance(message, ResultMessage):
            print(f"\nDone: {message.subtype}")

asyncio.run(main())

Para obter um tutorial mais completo, consulte o Guia de início rápido.

Ferramentas internas¶

Seu agente pode ler arquivos, executar comandos, executar SQL e pesquisar bases de código sem configuração adicional. As ferramentas disponíveis podem variar de acordo com os recursos do ambiente e do tempo de execução:

Sessões multiturno¶

Você pode manter o contexto entre várias trocas. O agente retém o conhecimento dos arquivos lidos, das análises realizadas e do histórico de conversas:

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({ cwd: process.cwd() });

await session.send("Read the authentication module");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

// Second turn - "it" refers to the auth module from context
await session.send("Now find all places that call it");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

await session.close();

from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions

async with CortexCodeSDKClient(CortexCodeAgentOptions()) as client:
    await client.query("Read the authentication module")
    async for msg in client.receive_response():
        pass  # process messages

    # Second turn - "it" refers to the auth module from context
    await client.query("Now find all places that call it")
    async for msg in client.receive_response():
        pass  # process messages

Você também pode continuar uma sessão anterior ou bifurcá-la em uma nova:

// Continue the most recent conversation
const session = await createCortexCodeSession({
  cwd: process.cwd(),
  continue: true,
});

// Or fork a resumed session into a new session ID
const forked = await createCortexCodeSession({
  cwd: process.cwd(),
  resume: "previous-session-id",
  forkSession: true,
});

# Continue the most recent conversation
async with CortexCodeSDKClient(
    CortexCodeAgentOptions(continue_conversation=True)
) as client:
    await client.query("What were we working on?")

# Or fork a resumed session into a new session ID
async with CortexCodeSDKClient(
    CortexCodeAgentOptions(resume="previous-session-id", fork_session=True)
) as client:
    await client.query("Let's try a different approach")

Servidores MCP¶

Você pode se conectar a sistemas externos por meio do Model Context Protocol:

from cortex_code_agent_sdk import CortexCodeAgentOptions

options = CortexCodeAgentOptions(
    mcp_servers={
        "my-tools": {
            "command": "node",
            "args": ["my-mcp-server.js"],
        },
    },
)

Ganchos¶

Você pode executar código personalizado em pontos-chave do ciclo de vida do agente. Os eventos de gancho disponíveis incluem PreToolUse, PostToolUse, Stop, UserPromptSubmit e muito mais. Os ganchos são compatíveis com SDKs Python e TypeScript. Consulte a Referência do SDK Python ou a Referência do SDK TypeScript para obter detalhes.

Saída estruturada¶

Você pode forçar o agente a retornar uma resposta correspondente a um esquema JSON:

const result = query({
  prompt: "Analyze this codebase",
  options: {
    cwd: ".",
    outputFormat: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          languages: { type: "array", items: { type: "string" } },
          summary: { type: "string" },
        },
        required: ["languages", "summary"],
      },
    },
  },
});

Para obter mais informações, consulte Saída estruturada.

Controle de sessão¶

Você pode controlar o comportamento do agente por meio das opções de sessão:

Inferência entre regiões¶

A disponibilidade do modelo varia de acordo com a região. Um administrador da conta pode habilitar a inferência entre regiões para acessar modelos não disponíveis localmente:

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_US';

Para obter mais informações, consulte Inferência entre regiões.