Skip to content

genius-agent

A production-grade Agent (A2A) + MCP orchestration server for agentic AI, built on the agent-utilities core.

Official documentation

This site is the canonical reference for genius-agent, maintained alongside every release.

PyPI MCP Server License GitHub

Overview

genius-agent is a fully integrated Pydantic-AI graph agent and Model Context Protocol (MCP) surface for the agent-utilities ecosystem. It provides:

  • An integrated graph agent — a Pydantic-AI agent that communicates over the Agent Control Protocol (ACP), drives the Agent Web UI (AG-UI), and runs an interactive terminal interface.
  • A consumed MCP tool surface — the agent connects to any MCP server declared in mcp_config.json (or a remote endpoint via MCP_URL), composing their tools into a single orchestration plane.
  • A native governed source tool — the separate genius-mcp entry point exposes the signed genius_ingest_search contract for bounded web search and idempotent epistemic-graph ingestion.
  • Enterprise security and telemetry inherited from agent-utilities — Eunomia policy enforcement, OIDC token delegation, OpenTelemetry export, and native Langfuse tracing, with guardrails enabled by default.

The agent remains inactive when credentials are absent: provide a model provider key and a system prompt and the graph agent comes online.

Explore the documentation

  • Installation — pip, source, extras, and the prebuilt Docker image.
  • Deployment — run the agent server, Docker Compose, Caddy + Technitium.
  • Usage — the agent, the MCP tool surface, and the CLI.
  • Overview — capabilities, enterprise readiness, and configuration.
  • Concepts — the CONCEPT:GENIUS-* registry.

Quick start

pip install "genius-agent[all]"
export API_KEY=your_model_provider_key
genius-agent --provider openai --model-id gpt-4o

The agent server starts with the Agent Web UI and ACP enabled. To connect it to a remote MCP tool surface:

export MCP_URL=http://your-mcp-host:8000/mcp
genius-agent --provider openai --model-id gpt-4o --host 0.0.0.0 --port 9000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, transports, reverse proxy, DNS).

Packaged governance

Runtime endpoints, credentials, and machine locations are injected by the launcher and are never part of the packaged configuration.

  • One comprehensive canonical skill, with specialist procedures retained as referenced workflows.
  • A signed connector capability manifest plus ontology, SHACL shapes, mappings, fixtures, migrations, and certification metadata.
  • Privacy-safe delegation through GraphOS using non-personal agent aliases.

See Configuration, trust, and privacy for the operator contract.