Qoder CN Series:Quickstart

Pré-requisitos

• Uma conta Qoder

• Um ambiente de terminal (macOS, Linux ou WSL)

• curl e jq (opcional, para formatar a saída JSON)

Etapa 1: Obter um PAT

1. Faça login no Console do Qoder.

2. Acesse Settings > Personal Access Tokens.

3. Clique em Create Token e defina um nome e uma data de expiração.

4. Copie o token e configure-o como variável de ambiente:

export QODER_PAT="your-token-here"

Etapa 2: Selecionar um ambiente

Liste os 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 .

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: Criar um agente

Defina um agente de uso 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 .

Etapa 4: Criar uma sessão

Criar uma sessão exige dois parâmetros: agent (ID ou objeto do agente) e environment_id (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 .

Etapa 5: Enviar uma mensagem e receber eventos

Envie uma mensagem de usuário para a sessão e receba as respostas do agente em tempo real por um fluxo 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"

Perguntas frequentes

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

R: Verifique se a variável de ambiente $QODER_PAT está configurada 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: Confirme se o corpo da requisição é um JSON válido. Certifique-se de que o campo model contenha um valor aceito (como "ultimate") e que o campo tools seja um array.

P: Por que minha sessão permanece em estado ocioso e não recebe eventos?

R: Após a criação, a sessão fica ociosa por padrão. Envie um evento user.message para acionar o agente. Verifique se você executou a Etapa 5 corretamente.

P: Como proceder se a conexão do fluxo 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>. Assim, o servidor retoma o envio de eventos exatamente de 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.

Próximas etapas

• Definir um agente — Conheça todos os campos de configuração de agentes.

• Ambientes em nuvem — Personalize seus ambientes de execução.

• Iniciar uma sessão — Aprofunde-se no gerenciamento de sessões.