Chat API

Chat API

Overview

The Chat API provides streaming chat functionality with the PTC agent. Responses are delivered in real-time via Server-Sent Events (SSE), enabling progressive display of agent reasoning, tool calls, and generated content.

Endpoints

Stream Chat

POST /api/v1/chat/stream

Stream PTC agent responses as Server-Sent Events. This is the primary endpoint for interacting with the agent.

Features:

• Creates or reuses a Daytona sandbox session per workspace
• Streams agent responses in real-time
• Supports tool execution and file operations
• Handles interrupts for human-in-the-loop (HITL) review
• Background execution with event buffering

Request Headers

Request Body

{
  "workspace_id": "workspace-uuid",
  "thread_id": "__default__",
  "messages": [
    {
      "role": "user",
      "content": "Write a hello world script in Python"
    }
  ],
  "plan_mode": false,
  "locale": "en-US",
  "timezone": "America/New_York"
}

Response 200 OK

Content-Type: text/event-stream

event: message_chunk
data: {"content": "I'll write a", "agent": "assistant"}

event: message_chunk
data: {"content": " Python script", "agent": "assistant"}

event: tool_calls
data: {"tool_name": "write_file", "arguments": {"path": "hello.py", "content": "print('Hello World')"}}

event: tool_call_result
data: {"tool_name": "write_file", "result": "File created successfully"}

event: done
data: {"status": "completed", "thread_id": "abc-123"}

Errors

Example

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-789" \
  -d '{
    "workspace_id": "ws-abc123",
    "messages": [{"role": "user", "content": "Write a hello world script"}]
  }'

Reconnect to Workflow

GET /api/v1/chat/stream/{thread_id}/reconnect

Reconnect to a running or completed workflow. Supports event replay for seamless reconnection after disconnects.

Path Parameters

Query Parameters

Response 200 OK

Content-Type: text/event-stream

Replays buffered events, then streams live events if workflow is still running.

Errors

Example

curl -N "http://localhost:8000/api/v1/chat/stream/abc-123/reconnect?last_event_id=42"

Stream Subagent Status

GET /api/v1/chat/stream/{thread_id}/status

Stream subagent_status updates for background subagents after the main response finishes. The stream closes once active_tasks is empty.

Path Parameters

Response 200 OK

Content-Type: text/event-stream

event: subagent_status
data: {"thread_id": "abc-123", "active_tasks": [], "completed_tasks": ["Task-1"]}

Cancel Workflow

POST /api/v1/chat/cancel/{thread_id}

Cancel a running PTC workflow.

Path Parameters

Response 200 OK

{
  "status": "cancelled",
  "thread_id": "abc-123"
}

Example

curl -X POST "http://localhost:8000/api/v1/chat/cancel/abc-123"

Get Workflow Status

GET /api/v1/chat/status/{thread_id}

Get status of a PTC workflow.

Path Parameters

Response 200 OK

{
  "thread_id": "abc-123",
  "status": "running",
  "workspace_id": "ws-abc123",
  "sandbox_id": "sandbox-789",
  "started_at": "2025-01-15T10:30:00Z",
  "completed_at": null,
  "error": null
}

Errors

Get Active Sessions

GET /api/v1/chat/sessions

Get information about active PTC sessions.

Response 200 OK

{
  "active_sessions": 5,
  "message": "PTC Session Service active"
}

SSE Event Types

Content Events

Control Events

Subagent Status Events

Artifact Events

Artifact Structure:

• artifact_type: Type discriminator (e.g., "file_operation", "todo_update")
• artifact_id: Unique ID derived from tool_call_id
• agent: Agent that created the artifact
• timestamp: ISO 8601 timestamp
• status: "completed" or "failed"
• payload: Type-specific data (varies by artifact_type)

For file_operation payload:

• operation: "write_file" or "edit_file"
• file_path: Full path to the file
• line_count: Number of lines
• content: File content (write_file only)
• old_string, new_string: Diff content (edit_file only)
• error: Error message (failed status only)

For todo_update payload:

• todos: Array of todo items with content, status, activeForm
• total: Total number of todos
• completed: Count of completed todos
• in_progress: Count of in-progress todos
• pending: Count of pending todos
• error: Error message (failed status only)

SSE Event Data Schemas

message_chunk

{
  "content": "Hello, I'll help you with...",
  "agent": "assistant",
  "role": "assistant"
}

tool_calls

{
  "tool_name": "write_file",
  "arguments": {
    "path": "/workspace/hello.py",
    "content": "print('Hello World')"
  },
  "tool_call_id": "call_abc123"
}

interrupt

{
  "interrupt_id": "int_xyz",
  "reason": "plan_review",
  "actions": [
    {
      "action_id": "action_1",
      "type": "write_file",
      "description": "Create hello.py"
    }
  ]
}

error

{
  "thread_id": "abc-123",
  "error": "Connection timeout",
  "type": "workflow_error",
  "error_class": "TimeoutError"
}

artifact (todo_update)

{
  "artifact_type": "todo_update",
  "artifact_id": "call_abc123",
  "agent": "ptc",
  "timestamp": "2025-01-15T10:30:00Z",
  "status": "completed",
  "payload": {
    "todos": [
      {
        "content": "Implement user authentication",
        "status": "completed",
        "activeForm": "Implementing user authentication"
      },
      {
        "content": "Add unit tests",
        "status": "in_progress",
        "activeForm": "Adding unit tests"
      },
      {
        "content": "Update documentation",
        "status": "pending",
        "activeForm": "Updating documentation"
      }
    ],
    "total": 3,
    "completed": 1,
    "in_progress": 1,
    "pending": 1
  }
}

HITL (Human-in-the-Loop) Resume

To resume from an interrupt, send a new request with the hitl_response field:

{
  "thread_id": "abc-123",
  "hitl_response": {
    "interrupt_id_1": {
      "decisions": [
        {"type": "approve", "message": null},
        {"type": "reject", "message": "Please use a different approach"}
      ]
    }
  },
  "messages": [{"role": "user", "content": "Continue"}]
}

Skill Loading

Use additional_context to load skill instructions for the agent. Skills are markdown-based instruction files that extend agent capabilities.

Skill Context Structure:

{
  "type": "skills",
  "name": "skill-name",
  "instruction": "Optional additional instruction for the skill"
}

Example: User Onboarding with Skill

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-789" \
  -d '{
    "workspace_id": "ws-abc123",
    "messages": [{"role": "user", "content": "Hi! I am new here and would like to set up my profile."}],
    "additional_context": [
      {
        "type": "skills",
        "name": "user-profile",
        "instruction": "Help the user with first time onboarding. Reference the skills/user-profile/onboarding.md for details. You should use load_skill tool to load the user-profile skill before calling any of the tools."
      }
    ]
  }'

The agent will load the skill's SKILL.md file and follow its instructions when processing the request.

Model Selection

The llm_model field allows you to override the default LLM model on a per-request basis. Available models are defined in src/llms/manifest/models.json.

Popular Models:

Example: Using a specific model

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-789" \
  -d '{
    "workspace_id": "ws-abc123",
    "llm_model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Explain quantum computing"}]
  }'

Notes:

• Model selection is optional; defaults to the model configured in agent_config.yaml
• Invalid model names will result in configuration errors
• Some models support reasoning/thinking modes (configured in models.json)
• Model costs vary significantly; check provider pricing

Health Check

GET /health

Health check endpoint (unversioned).

Response 200 OK

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "0.1.0",
  "service": "ptc-agent"
}