xAgent

xAgent is a single-agent runtime with three entry points: Python API, CLI, and HTTP server.

• Chat via CLI, Python API, or HTTP
• One continuous agent-level message stream
• Speaker-aware messages via user_id
• Built-in Web UI and streaming responses
• Tool calling, MCP integration, and image input
• Long-term memory enabled by default with local storage

Quick Start

Install

pip install myxagent

Set environment variables

export OPENAI_API_KEY=your_openai_api_key

Start the CLI

xagent-cli

Single-shot mode:

xagent-cli --ask "Hello"

Message Model

Every chat appends to the agent's continuous message stream.

• user_id identifies the current speaker
• recent context is pulled from the agent's global recent-message window
• single-user and multi-user interactions use the same runtime model

HTTP API

Start the server:

xagent-server

Open the Web UI automatically:

xagent-server --open

Send a chat message:

curl -X POST "http://localhost:8010/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "user_message": "Remember that my favorite city is Hangzhou."
  }'

Another speaker in the same conversation:

curl -X POST "http://localhost:8010/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "bob",
    "user_message": "Please summarize Alice'"'"'s plan and list the top risks."
  }'

Clear the message stream:

curl -X POST "http://localhost:8010/clear_messages"

Image input:

curl -X POST "http://localhost:8010/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "user_message": "Describe this image.",
    "image_source": "https://example.com/image.jpg"
  }'

Python API

import asyncio
from xagent.core import Agent


async def main():
    agent = Agent(model="gpt-5.4-mini")

    reply = await agent.chat(
        user_message="Hello",
        user_id="alice",
    )
    print(reply)

    follow_up = await agent.chat(
        user_message="Summarize what the conversation has agreed on so far.",
        user_id="bob",
    )
    print(follow_up)


asyncio.run(main())

image_source accepts a single value or a list of values. Each item can be an image URL, local file path, or base64 data URI.

Configure with agent.yaml

Generate a starter config:

xagent-cli --init

Example:

agent:
  name: "Assistant"
  system_prompt: |
    You are a helpful AI assistant.
    Answer clearly and accurately.
  model: "gpt-5.4-mini"

  capabilities:
    tools:
      - "web_search"

server:
  host: "0.0.0.0"
  port: 8010

Run with config:

xagent-cli --config config/agent.yaml --toolkit_path my_toolkit
xagent-server --config config/agent.yaml --toolkit_path my_toolkit --open

Documentation

• Documentation Index
• Getting Started
• Configuration Reference
• API Reference
• Memory System
• Message Storage Inheritance
• Examples

License

This project is licensed under the MIT License. See LICENSE.