Quickstart - : Central de Documentação do Alibaba Cloud

Coloque seu primeiro Qoder cloud Agent em funcionamento em 5 etapas: obtenha um token, selecione um ambiente, crie um agente, crie uma sessão e envie e receba mensagens. Tudo que você precisa é do curl — nenhuma instalação de SDK é necessária.

Importante

O novo site de documentação do Qoder CN já está disponível. O conteúdo deste site pode não refletir os recursos e as alterações mais recentes do product. Acesse docs.qoder.cn para consultar a documentação mais atualizada do product.

Pré-requisitos

Uma conta Qoder
Um ambiente de terminal (macOS, Linux ou WSL)
curl e jq (opcional, para formatar a saída JSON)

Para usuários Windows: Os comandos neste documento utilizam sintaxe bash. Recomendamos usar o Git Bash (incluído no Git for Windows) ou o WSL (instale com wsl --install). Caso use PowerShell, adapte os comandos: defina uma variável de ambiente com $env:QODER_PAT="your-token", use curl.exe para contornar o alias curl do PowerShell e instale o jq separadamente (por exemplo, winget install jqlang.jq).

Etapa 1: Obtenha um PAT

Acesse o Qoder Console e faça login.
Acesse Settings > Personal Access Tokens.
Clique em Create Token, defina um nome e uma data de expiração.
Copie o token e defina-o como uma variável de ambiente:

export QODER_PAT="your-token-here"

O token é exibido apenas uma vez, no momento da criação. Salve-o em um local seguro imediatamente. Para maior praticidade, adicione o comando export ao arquivo de inicialização do seu shell, como ~/.bashrc ou ~/.zshrc.

Etapa 2: Selecione um ambiente

Liste seus ambientes disponíveis para obter um ID de ambiente:

curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq .

Se a resposta retornar "data": [] (um array vazio), sua conta ainda não possui ambientes. Crie um da seguinte forma:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "config": {"type": "cloud", "networking": {"type": "unrestricted"}}}' | jq .

Etapa 3: Crie um agente

Defina um agente de propósito geral com ferramentas de shell:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "instructions": "You are a helpful coding assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }' | jq .

Anote o campo id na resposta (por exemplo, agent_019e...). Você precisará dele para criar uma sessão na próxima etapa.

Etapa 4: Crie uma sessão

A criação de uma sessão requer dois parâmetros: agent (o ID ou objeto do agente) e environment_id (o ID do ambiente).

Vincule o agente a um ambiente para criar uma instância em execução:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_YOUR_AGENT_ID",
    "environment_id": "env_YOUR_ENV_ID"
  }' | jq .

Após a criação, a sessão entra em estado ocioso. O agente começa a executar somente após você enviar uma mensagem na próxima etapa.

Etapa 5: Envie uma mensagem e receba eventos

Envie uma mensagem de usuário para a sessão e receba as respostas do agente em tempo real por meio de um stream SSE:

# Send a message
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": [{"type": "text", "text": "Write a Python function that calculates fibonacci numbers"}]
  }'

# Receive the SSE event stream
curl -sN "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

A API envia um evento de heartbeat aproximadamente a cada 15 segundos para manter a conexão ativa. O campo content de um evento agent.message utiliza o formato de array: [{"type":"text","text":"..."}].

FAQ

P: O que fazer se eu receber um erro 401 Unauthorized?

R: Verifique se a variável de ambiente $QODER_PAT está definida corretamente e se o token não expirou. Se necessário, crie um novo token e atualize a variável de ambiente.

P: Por que recebo um erro 400 Bad Request ao criar um agente?

R: Verifique se o corpo da requisição é um JSON válido. Confirme que o campo model possui um valor válido (por exemplo, "ultimate") e que o campo tools é um array.

P: Por que minha sessão está presa no estado ocioso e não recebe eventos?

R: Uma sessão fica ociosa por padrão após a criação. É necessário enviar um evento user.message para acionar o agente. Verifique se a Etapa 5 foi executada corretamente.

P: O que fazer se a conexão do stream SSE for interrompida?

R: Recomendamos salvar o id do último evento recebido antes da desconexão (por exemplo, evt_...). Ao reconectar, inclua o parâmetro de consulta ?after_id=<last_event_id>. O servidor retomará o envio de eventos a partir do ponto onde parou.

P: Por que GET /environments retorna um array vazio?

R: Contas novas podem não ter um ambiente pré-configurado. Crie um conforme descrito na Etapa 2.