> ## Documentation Index
> Fetch the complete documentation index at: https://studio.chat-atp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Streaming (SSE)

> Handle real-time autonomous agent events

ChatATP uses Server-Sent Events (SSE) to stream real-time updates as agents process messages, execute tools, and generate responses.

## SDK Developer Scenarios: Event Streams

The ChatATP SDK handles parsing the underlying HTTP stream. Here are the core scenarios you should handle when reading events from the `chatStream` method.

### Scenario 1: Basic Text Response

When a user asks a simple question and the agent responds without needing tools.

```typescript theme={null}
for await (const event of client.chatStream({ ... })) {
  switch (event.type) {
    case "conversation.message.created":
      // Initial acknowledgment
      break;
    case "message.created":
      // User message saved
      break;
    case "agent.response.delta":
      // Incremental text chunks from the LLM
      process.stdout.write(event.data.delta);
      break;
    case "agent.response.completed":
      // Finalization of the agent's full response
      console.log("\nFinished text:", event.data.content);
      break;
  }
}
```

### Scenario 2: Autonomous Tool Execution

When the agent decides to invoke an internal tool during its response cycle.

```typescript theme={null}
for await (const event of client.chatStream({ ... })) {
  switch (event.type) {
    case "tool.execution.started":
      // 1. The agent decides to call a tool
      console.log(`Running tool: ${event.data.name}`, event.data.arguments);
      break;
    case "tool.execution.completed":
      // 2. The backend executes the tool and streams back the result
      console.log(`Tool ${event.data.name} completed. OK: ${event.data.ok}`);
      console.log(`Result: ${event.data.result}`);
      break;
    case "agent.response.delta":
      // 3. The agent reasons about the tool response and streams text
      process.stdout.write(event.data.delta);
      break;
    case "agent.response.completed":
      // 4. Final completion payload with full metadata
      console.log("Response complete. Tools used:", event.data.tool_calls);
      break;
  }
}
```

### Scenario 3: Error Encountered

When something goes wrong in the backend or tool execution fails.

```typescript theme={null}
for await (const event of client.chatStream({ ... })) {
  switch (event.type) {
    case "tool.execution.completed":
      if (!event.data.ok) {
        console.error(`Tool failed: ${event.data.result}`);
      }
      break;
    case "error":
      // If the LLM integration completely drops or a critical pipeline error occurs
      console.error(`Critical Error: ${event.data.message}`);
      break;
  }
}
```

### SDK Integration Tips:

1. **State Management**: Keep an array/dictionary in memory keyed by `tool_call_id`. When `tool.execution.started` arrives, push the placeholder. When `tool.execution.completed` arrives, update the matching placeholder with the `result` string.
2. **Text Accumulation**: Simply concatenate the strings from `agent.response.delta` sequentially to render typewriter effects.