yao/openapi/agent/README.md

Agent API

This document describes the RESTful API for AI agent interactions and chat completions in Yao applications.

Base URL

All endpoints are prefixed with the configured base URL followed by /agent (e.g., /v1/agent).

Authentication

All endpoints require OAuth authentication via the configured OAuth provider.

Overview

The Agent API provides AI-powered chat completion capabilities with support for:

• Server-Sent Events (SSE) - Real-time streaming responses
• Context Management - Persistent chat sessions with history
• Assistant Selection - Multiple AI assistants with different capabilities
• Flexible Parameters - Configurable behavior for different use cases
• Session Management - Automatic session handling with user identification

Endpoints

Chat Completions

Create AI chat completions with streaming responses using Server-Sent Events.

GET /chat/completions?content={content}&chat_id={chat_id}&assistant_id={assistant_id}&context={context}&silent={silent}&history_visible={history_visible}&client_type={client_type}
POST /chat/completions

Note: This is a temporary implementation for full-process testing, and the interface may undergo significant global changes in the future.

Query Parameters (GET) / Form Data (POST):

• content (required): The user's message or question
• chat_id (optional): Chat session identifier (auto-generated if not provided)
• assistant_id (optional): Specific assistant to use (defaults to system default)
• context (optional): Additional context for the conversation
• silent (optional): Silent mode flag ("true"/"false" or "1"/"0")
• history_visible (optional): Whether chat history is visible ("true"/"false" or "1"/"0")
• client_type (optional): Client type identifier for customization

Headers:

Authorization: Bearer {access_token}

Response Headers:

Content-Type: text/event-stream;charset=utf-8
Cache-Control: no-cache
Connection: keep-alive

Example GET Request:

curl -X GET "/v1/agent/chat/completions?content=Hello%2C%20how%20are%20you%3F&chat_id=chat_123&assistant_id=mohe" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: text/event-stream"

Example POST Request:

curl -X POST "/v1/agent/chat/completions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: text/event-stream" \
  -d "content=Hello, how are you?&chat_id=chat_123&assistant_id=mohe"

Response (Server-Sent Events):

The response is streamed as Server-Sent Events with the following format:

data: {"type":"message","content":"Hello! I'm doing well, thank you for asking.","role":"assistant","timestamp":1640995200}

data: {"type":"done","chat_id":"chat_123","session_id":"session_456"}

Response Data Types:

• message - Content chunk from the AI assistant
• error - Error message if something goes wrong
• done - Indicates completion of the response

Success Response Example:

{
  "type": "message",
  "content": "Hello! I'm an AI assistant created by Yao. How can I help you today?",
  "role": "assistant",
  "chat_id": "chat_123",
  "timestamp": 1640995200
}

Completion Response:

{
  "type": "done",
  "chat_id": "chat_123",
  "session_id": "session_456"
}

Parameters in Detail

Content Parameter

The content parameter is the main user input:

• Required for all requests
• Can be a question, command, or conversation message
• Supports natural language input
• Maximum length depends on assistant configuration

Chat ID Management

The chat_id parameter manages conversation continuity:

• Auto-generated if not provided (format: chat_{timestamp})
• Persistent across multiple requests for the same conversation
• Unique identifier for each chat session
• Used for conversation history and context management

Assistant Selection

The assistant_id parameter allows choosing specific AI assistants:

• Optional - defaults to system default assistant
• Different assistants may have different capabilities, knowledge bases, or personalities
• Examples: mohe, developer, analyst

Context and Behavior

Additional parameters for fine-tuning behavior:

• context - Provides additional context for better responses
• silent - Controls verbose/quiet response modes
• history_visible - Controls whether conversation history affects responses
• client_type - Allows client-specific customizations

Error Responses

All endpoints return standardized error responses via Server-Sent Events:

data: {"type":"error","error":"invalid_request","error_description":"content is required"}

Common Error Types:

• invalid_request - Missing required parameters
• unauthorized - Authentication failure
• assistant_not_found - Invalid assistant ID
• internal_error - Server processing error

HTTP Status Codes:

• 200 - Success (streaming response)
• 400 - Bad Request (missing content parameter)
• 401 - Unauthorized (authentication required)
• 500 - Internal Server Error

Session Management

The Agent API automatically manages sessions:

Session Creation

• Automatic session creation when __sid is not present
• UUID generation for new sessions
• Session persistence across requests

Session Context

• User identification through session data
• Conversation history maintained per chat_id
• Context preservation between messages

Real-Time Streaming

The API uses Server-Sent Events for real-time communication:

Connection Management

• Keep-alive connections for streaming
• Automatic reconnection support
• Graceful error handling

Event Types

• message - Streaming content chunks
• error - Error notifications
• done - Completion indicators

Example Workflows

Simple Chat Interaction

1. Start a conversation:

curl -X GET "/v1/agent/chat/completions?content=What%20is%20Yao?" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: text/event-stream"

2. Continue the conversation:

curl -X GET "/v1/agent/chat/completions?content=Tell%20me%20more%20about%20its%20features&chat_id=chat_123" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: text/event-stream"

Assistant-Specific Interaction

1. Use a specific assistant:

curl -X POST "/v1/agent/chat/completions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: text/event-stream" \
  -d "content=Help me debug this code&assistant_id=developer&chat_id=debug_session_456"

Context-Aware Conversation

1. Provide additional context:

curl -X GET "/v1/agent/chat/completions?content=Optimize%20this%20query&context=PostgreSQL%20database%20with%20large%20user%20table&assistant_id=analyst" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: text/event-stream"

Silent Mode Operation

1. Use silent mode for concise responses:

curl -X GET "/v1/agent/chat/completions?content=Generate%20user%20model&silent=true&client_type=api" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: text/event-stream"

JavaScript Client Example

Here's how to consume the streaming API in JavaScript:

const eventSource = new EventSource(
  "/v1/agent/chat/completions?content=Hello&chat_id=chat_123",
  {
    headers: {
      Authorization: "Bearer " + accessToken,
    },
  }
);

eventSource.onmessage = function (event) {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case "message":
      console.log("Assistant:", data.content);
      break;
    case "error":
      console.error("Error:", data.error_description);
      break;
    case "done":
      console.log("Conversation completed");
      eventSource.close();
      break;
  }
};

eventSource.onerror = function (error) {
  console.error("Connection error:", error);
};

Integration Considerations

Performance

• Streaming responses reduce perceived latency
• Connection pooling for multiple concurrent chats
• Automatic session cleanup prevents memory leaks

Security

• OAuth 2.1 authentication required for all requests
• Session-based access control
• Input validation and sanitization
• Rate limiting (configured at server level)

Scalability

• Stateless design (session data in external store)
• Load balancer compatible (sticky sessions not required)
• Horizontal scaling support

Development Notes

Important: This is a temporary implementation for full-process testing. The interface design and functionality may undergo significant global changes in future versions. Consider this API experimental and subject to breaking changes.

Current Limitations

• Limited error recovery mechanisms
• Basic assistant selection logic
• Simplified context management
• Minimal response formatting options

Future Enhancements

Future versions may include:

• Enhanced context management
• Advanced assistant capabilities
• Improved error handling
• Extended parameter options
• WebSocket support as alternative to SSE

This Agent API provides a foundation for AI-powered interactions in Yao applications with real-time streaming capabilities and flexible configuration options.