yao/agent

Yao Agent

A powerful AI assistant framework for building intelligent conversational agents with tool integration, knowledge base search, and multi-agent orchestration.

Quick Start

1. Create an Assistant

assistants/
└── my-assistant/
    ├── package.yao      # Configuration
    ├── prompts.yml      # System prompts
    └── locales/
        └── en-us.yml    # Translations

package.yao

{
  "name": "{{ name }}",
  "connector": "gpt-4o",
  "description": "{{ description }}",
  "placeholder": {
    "title": "{{ chat.title }}",
    "prompts": ["{{ chat.prompts.0 }}"]
  }
}

prompts.yml

- role: system
  content: |
    You are a helpful assistant.

locales/en-us.yml

name: My Assistant
description: A helpful AI assistant
chat:
  title: New Chat
  prompts:
    - How can I help you today?

2. Add Hooks (Optional)

Create src/index.ts for custom logic:

import { agent } from "@yao/runtime";

function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
  // Preprocess messages before LLM call
  return { messages };
}

function Next(ctx: agent.Context, payload: agent.Payload): agent.Next {
  // Post-process LLM response
  return null;
}

3. Test (Optional)

# Run tests
yao agent test -i "Hello, how are you?"

# Run tests from JSONL file
yao agent test -i tests/inputs.jsonl -v

# Extract results for review
yao agent extract output-*.jsonl

4. Run

yao start

Access via API: POST /v1/chat/completions

Examples

Hook: Route to Specialist

// src/index.ts
function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
  const last = messages[messages.length - 1]?.content || "";
  if (last.includes("refund")) {
    return { delegate: { agent_id: "refund-specialist", messages } };
  }
  return null;
}

Database Query

// package.yao - Enable auto DB search
{ "db": { "models": ["orders", "products"] } }

# Test: Agent auto-generates QueryDSL and searches database
yao agent test -i "Find orders over $1000 from last month"

MCP Tools (Process Transport)

// mcps/tools.mcp.yao - Define MCP server with Yao Processes
{
  "label": "Tools",
  "transport": "process",
  "tools": {
    "search_orders": "models.order.Paginate",
    "create_order": "models.order.Create"
  }
}

// mcps/mapping/tools/schemes/search_orders.in.yao - Input schema
{
  "type": "object",
  "properties": {
    "keyword": { "type": "string" },
    "page": { "type": "integer" }
  },
  "x-process-args": [":arguments"]
}

// package.yao
{ "mcp": { "servers": [{ "server_id": "tools" }] } }

Sidebar Page (Display Data)

Pages render in the right sidebar during conversation to display structured data:

<!-- pages/result/result.html - Display query results -->
<div class="result-panel">
  <h3>{{ title }}</h3>
  <table s:if="{{ rows.length > 0 }}">
    <tr s:for="{{ rows }}" s:for-item="row">
      <td>{{ row.name }}</td>
      <td>{{ row.value }}</td>
    </tr>
  </table>
</div>

yao sui build agent    # Build pages

// In hook: send action to open page in sidebar
ctx.Send({
  type: "action",
  props: {
    name: "navigate",
    payload: {
      route: "/agents/my-assistant/result",
      title: "Query Results",
      query: { id: "123" }, // Passed as $query in page
    },
  },
});

Documentation

• Configuration - Assistant settings, connectors, options
• Prompts - System prompts and prompt presets
• Hooks - Create/Next hooks and agent lifecycle
• Context API - Messaging, memory, trace, MCP
• MCP Integration - Tool servers and resources
• Models - Assistant-scoped data models
• Search - Web, knowledge base, and database search
• Pages - Web UI for agents (SUI framework)
• Iframe Integration - Iframe communication with CUI
• Internationalization - Multi-language support
• Testing - Agent testing framework

Architecture

flowchart LR
    subgraph Request
        A[User Request]
    end

    subgraph Create["Create Hook"]
        B1[Preprocess Messages]
        B2[Configure LLM]
        B3[Delegate to Agent]
    end

    subgraph LLM["LLM Call"]
        C1[Load Prompts]
        C2[Generate Response]
    end

    subgraph Tools["Tool Execution"]
        D1[MCP Tools]
        D2[Search]
        D3[Memory]
    end

    subgraph Next["Next Hook"]
        E1[Process Results]
        E2[Transform Output]
        E3[Delegate to Agent]
    end

    subgraph Response
        F[Stream Response]
    end

    A --> Create
    Create --> LLM
    LLM --> Tools
    Tools --> Next
    Next --> Response
    Next -.->|Continue| LLM

API Endpoints

OpenAPI endpoints (base URL: /v1):

Endpoint	Method	Description
/v1/chat/completions	POST	Chat with assistant
/v1/chat/sessions	GET	List chat sessions
/v1/chat/sessions/:chat_id	GET	Get chat session
/v1/chat/sessions/:chat_id/messages	GET	Get messages
/v1/agent/assistants	GET	List assistants
/v1/agent/assistants/:id	GET	Get assistant details
/v1/file/:uploaderID	POST	Upload files
/v1/file/:uploaderID/:fileID	GET	Get file info
/v1/file/:uploaderID/:fileID/content	GET	Download file

License

This project is part of the Yao App Engine and follows the Yao Open Source License.