:Start a session

Ciclo de vida da sessão

1. Criar → idle

   Uma nova sessão entra no estado idle e aguarda entradas.

2. idle → processing

   Ao enviar um evento user.message, o status muda para processing.

3. processing → idle

   Quando o turno atual termina, a sessão retorna ao estado idle, pronta para o próximo turno.

4. processing → canceling → idle

   Quando você cancela uma sessão em execução, o status dela passa para canceling antes de retornar a idle. A sessão continua disponível para uso.

5. archived (estado terminal)

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

Uma sessão é uma máquina de estados com os seguintes status principais:

Campos

Crie uma sessão

Para criar uma sessão, especifique um agent e um environment_id.

Usar um ID de Agent (string)

Vincula a sessão à 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 (especifique a versão)

Vincula a sessão a uma versão específica do Agent para garantir um 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 requisiçã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 produção, especifique uma versão para evitar mudanças inesperadas de comportamento e atualize o Agent com segurança.

Formato do campo Agent

Transições de estado

Formato do corpo da requisição de evento

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

idle → processing

Ao enviar um evento user.message para uma sessão, o status dela 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 sessão retorna automaticamente para idle. Você recebe um evento session.status_idle por meio do fluxo de eventos.

Cancele uma sessão

É possível interromper uma sessão 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"

Recuperar 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, escute o evento SSE session.status_idle no final de cada turno. O campo usage desse evento contém a contagem de tokens desse 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 da sessão e do Agent

Uma sessão 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.

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

• Após a criação da sessão, modificar o Agent não afeta essa sessão.

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

Conversa de múltiplos turnos

As sessões suportam conversas de 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 ao status

Erros comuns ao enviar eventos para uma sessão:

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."
  }
}

Melhores práticas

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

2. Cancelamento oportuno — Cancele sessões desnecessárias para liberar recursos.

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

4. Tags com metadados — Use o campo metadata para registrar o contexto do negócio, como IDs de tarefas ou fontes de gatilho.

Perguntas frequentes

P: As sessões têm um mecanismo de tempo limite?

R: Uma sessão idle permanece retida por um período de tempo. O sistema pode arquivar automaticamente sessões inativas por um período prolongado. Crie sessões sob demanda e cancele-as após a conclusão das tarefas.

P: O que acontece se eu enviar uma mensagem para uma sessão com o status processing?

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

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

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

P: Como obtenho o histórico completo da conversa de uma sessão?

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

P: Uma sessão cancelada pode ser reutilizada?

R: Sim. Após cancelar uma sessão, o status dela passa automaticamente de canceling de volta para idle, e a sessão continua 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 sessão arquivada.