AgentID Protocol

Give your AI agent a persistent identity. Connect it anywhere.

Website · Dashboard · Pricing · Integrations

What is AgentID?

AgentID is an open protocol that gives every AI agent a portable identity — a handle, a persona, persistent memory, and a live activity log — that travels with it across tools and sessions.

Connect your agent from Claude Code, Cursor, Windsurf, OpenAI Agents SDK, or any HTTP-capable runtime. Your agent's memory and personality sync instantly, everywhere.

Your Agent ──MCP──► AgentID ──► Identity + Memory + Activity Log
           ──HTTP──►         ──► Studio Dashboard (real-time)

Features

• 🪪 Portable Identity — One @handle per agent. One persona that works in every tool.
• 🧠 Persistent Memory — Key/value facts that survive across sessions, tools, and runtimes.
• 📡 Activity Log — Every task, tool call, and step streamed live to your Studio dashboard.
• 🔌 MCP Server — Native integration for Claude Code, Cursor, Windsurf, and any MCP host.
• 🌐 HTTP Ingest — No-auth event reporting from any language or framework.
• 🗂️ Drive — Files, connectors, API keys, custom skills, and memory — all in one place your agent can reach.
• ⚡ Hosted Agents — Run a fully hosted agent on AgentID with no external API keys needed. Free tier included.
• 📤 Prompt Export — Export your agent's identity as a system prompt for any LLM (Claude, OpenAI, generic).

Quickstart — Claude Code (60 seconds)

1. Create your agent at agentid.live/app/agents — get your handle and MCP secret.

2. Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "agentid": {
      "type": "sse",
      "url": "https://agentid.live/api/mcp/YOUR_HANDLE",
      "headers": { "Authorization": "Bearer YOUR_MCP_SECRET" }
    }
  }
}

3. Restart Claude Code. Your agent now has memory, identity, and a live activity log.

Works the same way in Cursor, Windsurf, and any other MCP-compatible host.

Quickstart — HTTP (any language)

No auth. No SDK. Just POST.

curl -X POST https://agentid.live/api/studio/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "agent_handle": "myagent",
    "type": "task.completed",
    "title": "Summarised weekly report",
    "state": "done",
    "detail": "Processed 47 items, 3-paragraph summary",
    "tokens_used": 1840
  }'

{ "ok": true, "event_id": "evt_abc123", "run_id": "run_xyz" }

See examples/ for TypeScript and Python implementations.

Integration Paths

MCP Server

Endpoint: https://agentid.live/api/mcp/{handle}
Transport: SSE · Auth: Authorization: Bearer <mcp_secret>

Tools

report_activity

Report a task event to the Studio activity log.

report_activity({
  type: "task.started" | "task.progress" | "task.completed" | "task.failed",
  title: string,          // e.g. "Refactoring auth module"
  state: "thinking" | "working" | "idle" | "done" | "error",
  detail?: string,        // what specifically happened
  tokens_used?: number,
  platform?: string,      // "claude-code" | "cursor" | "api" | ...
  tool_name?: string,
  tool_input?: string,    // ≤200 chars
  tool_output?: string,   // ≤200 chars
  progress?: number,      // 0–100
  model?: string,
  duration_ms?: number,
})

write_memory

Persist a fact to the agent's shared memory.

write_memory({ key: "user_timezone", value: "Europe/Berlin" })

read_memory

Read all memory entries for this identity.

read_memory()
// Returns: "key: value\nkey2: value2\n..."

search_memory

Semantic search over the agent's memory.

search_memory({ query: "what does the user prefer?" })

Resources

agentid://identity/{handle}  — full persona: name, role, values, style, memory
agentid://skill/{handle}     — operational protocol and usage examples
agentid://memory/{handle}    — live memory entries

HTTP Ingest API

Endpoint: POST https://agentid.live/api/studio/ingest · No auth required.

{
  agent_handle: string,       // required
  type: string,               // required — see event types below
  title: string,              // required — short headline

  run_id?: string,            // group events; auto-generated if omitted
  state?: "thinking" | "working" | "idle" | "done" | "error",
  detail?: string,
  platform?: string,
  action?: string,            // e.g. "search.web", "file.write"
  target?: string,            // e.g. "https://...", "file.txt"
  tool_name?: string,
  tool_input?: string,        // ≤200 chars
  tool_output?: string,       // ≤200 chars
  progress?: number,          // 0–100
  tokens_used?: number,
  model?: string,
  duration_ms?: number,
  metadata?: Record<string, unknown>,
}

Event Types

Agent Session Protocol

The recommended pattern for MCP-connected agents:

SESSION START
  1. report_activity(type="task.started", title="Session started", detail="<user request>")
  2. read agentid://identity/{handle}  →  load persona + memory

DURING EACH TASK
  • report_activity("task.started")    before starting
  • report_activity("task.progress")   at each meaningful step
  • report_activity("task.completed")  or "task.failed" — always close the loop

MEMORY
  • read_memory() at session start — load context
  • write_memory() when you learn a persistent fact — one key per fact

Identity Format

interface CanonicalPersona {
  name: string,
  tagline?: string,
  role?: string,
  mission?: string,
  values?: string[],
  communication_style?: {
    tone?: string,
    format?: string,
    length?: string,
  },
  expertise?: string[],
  behaviors?: { always?: string[], never?: string[] },
  goals?: string[],
  context?: string,
}

Prompt Export

Export your agent's identity as a system prompt for paste-based integration.

GET https://agentid.live/api/agents/{handle}/export?format=generic-prompt
Authorization: Bearer <mcp_secret>

Available formats: generic-prompt · claude · openai · molebook

Authentication

Get credentials from your agent dashboard.

Drive

Drive is your agent's persistent storage and toolbox — accessible from any runtime.

Manage at agentid.live/app/drive.

Hosted Agents

Run a fully hosted agent on AgentID — no external LLM subscription, no API keys.

Create one at agentid.live/app/agents/new.

Examples

• examples/ingest.ts — TypeScript HTTP ingest
• examples/ingest.py — Python HTTP ingest

Roadmap

• @agentid/sdk — TypeScript/JavaScript client
• npx @agentid/cli setup — auto-configure Claude Code, Cursor, Codex
• Webhook triggers — agent-to-agent event routing
• Agent-to-agent memory sharing

License

Protocol specification: MIT