Qoder CN Series:Start a session

Ciclo de vida da sessão

1. Create → idle

   Uma nova Session entra no estado idle e aguarda entrada.

2. idle → processing

   Após o envio de um evento user.message, o status muda para processing.

3. processing → idle

   Ao concluir o turno atual, a Session retorna ao estado idle, pronta para o próximo turno.

4. processing → canceling → idle

   Ao cancelar uma Session em execução, o status transita para canceling antes de retornar a idle. A Session permanece disponível para uso.

5. archived (estado terminal)

   O status archived é um estado terminal. Não é possível restaurar uma Session arquivada.

Uma Session funciona como uma máquina de estados com os seguintes status principais:

Campos

Criar uma sessão

Para criar uma Session, especifique um agent e um environment_id.

Usar um ID de Agent (string)

Vincula a Session à versão mais recente do Agent.

# Create a Session using an Agent ID
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_019e5ce0bf307a1a8f952eb814aea3d5",
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

Usar um objeto Agent (especificar versão)

Vincula a Session a uma versão específica do Agent para garantir comportamento consistente.

# Create a Session by specifying an Agent version
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": {
      "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "version": 2
    },
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

Uma solicitação bem-sucedida retorna uma resposta 201 Created:

{
  "id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "agent": {
    "created_at": "2026-05-18T10:00:00Z",
    "default_environment": "",
    "description": "",
    "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "instructions": "You are a code review expert.",
    "mcp_servers": [],
    "model": "ultimate",
    "name": "code-reviewer",
    "system": "You are a code review expert.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "type": "agent",
    "updated_at": "2026-05-18T10:00:00Z",
    "version": 2
  },
  "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "",
  "turn_status": "idle",
  "memory_store_ids": [],
  "resources": [],
  "vault_ids": [],
  "type": "session",
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}

Em ambientes de produção, especifique uma versão para evitar mudanças inesperadas de comportamento causadas por atualizações do Agent.

Formato do campo agent

Transições de estado

Formato do corpo da solicitação de eventos

O corpo da solicitação para POST /sessions/{id}/events deve ser um objeto contendo um array events. Cada evento no array inclui um campo content, composto por um array de blocos de conteúdo.

idle → processing

Ao enviar um evento user.message para uma Session, o status muda de idle para processing.

# Send a message to trigger processing
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{"type": "text", "text": "Analyze the code complexity of all Python files in the current directory."}]
    }]
  }' | jq .

processing → idle

Quando o processamento termina, a Session retorna automaticamente ao estado idle. Você recebe um evento session.status_idle pelo fluxo de eventos.

Cancelar uma sessão

É possível interromper uma Session em execução.

# Cancel a Session
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

Consultar sessões

# Retrieve a single Session
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
  -H "Authorization: Bearer $QODER_PAT"

# List all Sessions (with pagination)
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

Exemplo de resposta paginada:

{
  "data": [
    {
      "id": "sess_019e5ce0bf9074b69c3481e93771a522",
      "type": "session",
      "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "status": "idle",
      "turn_status": "idle",
      "title": "",
      "memory_store_ids": [],
      "vault_ids": [],
      "resources": [],
      "created_at": "2026-05-18T12:00:00Z",
      "updated_at": "2026-05-18T12:30:00Z"
    }
  ],
  "first_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "last_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "has_more": false
}

Uso de tokens

A API REST não retorna o uso de tokens por turno. Em vez disso, monitore o evento SSE session.status_idle ao final de cada turno. Seu campo usage contém as contagens de tokens daquele turno.

Exemplo de payload SSE session.status_idle:

{
  "type": "session.status_idle",
  "usage": {
    "input_tokens": 3840,
    "output_tokens": 2156,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

Vinculação de versão entre Session e Agent

Uma Session captura um snapshot da configuração do Agent no momento da criação.

• Use o formato de string "agent": "agent_xxx" para vincular à versão mais recente do Agent no momento da criação.

• Utilize o formato de objeto "agent": {"id": "agent_xxx", "version": N} para vincular a uma versão específica.

• Após a criação de uma Session, modificar o Agent não afeta essa Session.

• Para usar uma nova versão de um Agent, crie uma nova Session.

Conversa com múltiplos turnos

As Sessions suportam conversas com múltiplos turnos. Após enviar uma mensagem, aguarde o evento session.status_idle antes de enviar a próxima mensagem.

#!/bin/bash
# Multi-turn conversation example
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
SESSION_ID="sess_019e5ce0bf9074b69c3481e93771a522"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

# Turn 1: Make the initial request
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Create a Python Flask project scaffold."}]}]}'

# Wait for processing to complete... (poll or listen for SSE)
sleep 30

# Turn 2: Add a follow-up requirement
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Add unit tests and a CI configuration to the project."}]}]}'

Códigos de erro relacionados a status

Erros comuns ao enviar eventos para uma Session:

Exemplo de resposta de erro 409:

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion."
  }
}

Práticas recomendadas

1. Fixação de versão — Em ambientes de produção, sempre crie Sessions usando o formato {"id": ..., "version": ...}.

2. Cancelamento oportuno — Cancele Sessions desnecessárias para liberar recursos.

3. Monitoramento de uso — Verifique regularmente o campo usage para evitar custos inesperados.

4. Identificação com metadados — Utilize o campo metadata para registrar o contexto de negócios, como IDs de tarefas ou origens de gatilho.

Perguntas frequentes

P: As Sessions possuem um mecanismo de timeout?

R: Uma Session idle é retida por um período de tempo. Sessions inativas por um longo período podem ser arquivadas automaticamente. Crie Sessions sob demanda e cancele-as após a conclusão das tarefas.

P: O que acontece se eu enviar uma mensagem para uma Session que está no status processing?

R: A API retorna um HTTP 409 conflict_error. Cancele o turno atual ou aguarde a Session retornar ao estado idle antes de enviar uma nova mensagem.

P: Qual é o número máximo de turnos que uma Session suporta?

R: Não há limite rígido, mas o tamanho da janela de contexto do modelo impõe um limite prático. À medida que a conversa cresce, o conteúdo anterior pode ser truncado.

P: Como obtenho o histórico completo de conversas de uma Session?

R: Execute a operação GET /sessions/{id}/events para recuperar todos os eventos da Session, incluindo mensagens do usuário e respostas do Agent.

P: Uma Session cancelada pode ser reutilizada?

R: Sim. Após cancelar uma Session, o status transita automaticamente de canceling de volta para idle, e a Session permanece disponível. Envie o próximo user.message para continuar a conversa. Apenas o status archived é um estado terminal. Não é possível restaurar uma Session arquivada.

Próximos passos

• Visão geral — Conheça a arquitetura do Cloud Agents.

• Início rápido — Percorra um exemplo completo de ponta a ponta.

• Definir um Agent — Saiba mais sobre a configuração do Agent.

• Cloud Environments — Personalize seu ambiente de runtime.