Ao criar uma Mensagem, você pode definir "stream": true para transmitir incrementalmente a resposta usando server-sent events (SSE).

Streaming com SDKs

Nossos SDKs Python e Typescript oferecem várias maneiras de streaming. O SDK Python permite streams síncronos e assíncronos. Consulte a documentação em cada SDK para obter detalhes.

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Olá"}],
    model="claude-3-opus-20240229",
) as stream:
  for text in stream.text_stream:
      print(text, end="", flush=True)

Tipos de eventos

Cada server-sent event inclui um tipo de evento nomeado e dados JSON associados. Cada evento usará um nome de evento SSE (por exemplo, event: message_stop) e incluirá o type de evento correspondente em seus dados.

Cada stream usa o seguinte fluxo de eventos:

  1. message_start: contém um objeto Message com content vazio.
  2. Uma série de blocos de conteúdo, cada um com um evento content_block_start, um ou mais eventos content_block_delta e um evento content_block_stop. Cada bloco de conteúdo terá um index que corresponde ao seu índice no array content final da Mensagem.
  3. Um ou mais eventos message_delta, indicando alterações de nível superior no objeto Message final.
  4. Um evento message_stop final.

Eventos Ping

Os streams de eventos também podem incluir qualquer número de eventos ping.

Eventos de erro

Ocasionalmente, podemos enviar erros no stream de eventos. Por exemplo, durante períodos de alto uso, você pode receber um overloaded_error, que normalmente corresponderia a um HTTP 529 em um contexto sem streaming:

Exemplo de erro
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Sobrecarregado"}}

Outros eventos

De acordo com nossa política de versão, podemos adicionar novos tipos de eventos, e seu código deve lidar com tipos de eventos desconhecidos de maneira graciosa.

Tipos de Delta

Cada evento content_block_delta contém um delta de um tipo que atualiza o bloco content em um determinado index.

Delta de texto

Um delta de bloco de conteúdo text se parece com:

Delta de texto
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "lá amig"}}

Delta de JSON de entrada

Os blocos delta de JSON de entrada fazem parte do beta de uso de ferramentas.

Os deltas para blocos de conteúdo tool_use correspondem a atualizações para o campo input do bloco. Para oferecer suporte à granularidade máxima, os deltas são strings JSON parciais, enquanto o tool_use.input final é sempre um objeto.

Você pode acumular os deltas de string e analisar o JSON assim que receber um evento content_block_stop, usando uma biblioteca como Pydantic para fazer a análise parcial de JSON, ou usando nossos SDKs, que fornecem auxiliares para acessar valores incrementais analisados.

Um delta de bloco de conteúdo tool_use se parece com:

Delta de JSON de entrada
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Nota: Nossos modelos atuais suportam apenas a emissão de uma propriedade completa de chave e valor de input por vez. Assim, ao usar ferramentas, pode haver atrasos entre os eventos de streaming enquanto o modelo está trabalhando. Assim que uma chave e valor de input são acumulados, nós os emitimos como vários eventos content_block_delta com json parcial em pedaços para que o formato possa suportar automaticamente uma granularidade mais fina em modelos futuros.

Resposta de Stream HTTP bruto

Recomendamos fortemente que você use nossos SDKs de cliente ao usar o modo de streaming. No entanto, se você estiver criando uma integração direta de API, precisará lidar com esses eventos você mesmo.

Uma resposta de stream é composta por:

  1. Um evento message_start
  2. Potencialmente vários blocos de conteúdo, cada um contendo: a. Um evento content_block_start b. Potencialmente vários eventos content_block_delta c. Um evento content_block_stop
  3. Um evento message_delta
  4. Um evento message_stop

Pode haver eventos ping dispersos ao longo da resposta também. Consulte Tipos de eventos para obter mais detalhes sobre o formato.

Solicitação básica de streaming

Request
curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: messages-2023-12-15" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-3-opus-20240229",
  "messages": [{"role": "user", "content": "Olá"}],
  "max_tokens": 256,
  "stream": true
}'
Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-opus-20240229", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Olá"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Solicitação de streaming com uso de ferramenta

Nesta solicitação, pedimos ao Claude para usar uma ferramenta para nos dizer o clima.

Request
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: tools-2024-05-16" \
    -d '{
      "model": "claude-3-opus-20240229",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Obter o clima atual em um determinado local",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "A cidade e o estado, por exemplo, São Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "any"},
      "messages": [
        {
          "role": "user",
          "content": "Como está o clima em São Francisco?"
        }
      ],
      "stream": true
    }'
Response
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-3-haiku-20240307","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Ok"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" vamos"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" verificar"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" o"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" clima"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" para"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" São"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"São"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}