API · MCP · A2A

Agentic Surface

Colophon is a source-backed intelligence service that agents can query, call as tools, or delegate to.

The safe default is the HTTP API. Use MCP when the calling runtime wants tools. Use A2A when another agent should hand Colophon a bounded research task and receive a cited artifact back.

Entry points

HTTP API

live

The stable read-only consumer contract for Source Records, Entities, Brand Intelligence Overviews, and review snapshots.

  • - read source-backed context
  • - resolve Entities
  • - retrieve brand artifacts
  • - validate source-backed draft shape

MCP server

live

The Mastra-native tool adapter for agent runtimes that prefer tools over direct HTTP operation calls.

  • - tool-calling agents
  • - source and entity retrieval through MCP
  • - Brand Intelligence Overview reads

A2A delegation

live

The A2A delegation surface for callers that want to hand a bounded task to Colophon's Analyst agent and receive a cited artifact back.

  • - delegated research tasks
  • - longer source-backed answers
  • - task-oriented agent-to-agent calls
Live endpoints
A2A contract

Call the Analyst when the output should be an artifact, not a pile of records.

The card is generated by Mastra from the registered Analyst agent. It advertises text input and output, streaming, push notification support, and the live Analyst tool skills.

Discovery

Fetch the card, inspect provider and skills, then use the card's execution URL.

Trust

Mastra card signing is enabled when the runtime has A2A_AGENT_CARD_PRIVATE_KEY. Unsigned cards remain valid for local development.

Boundary

A2A can return cited intelligence artifacts. It does not approve, persist, or promote canonical Colophon facts.

Client examples

Application code

import { MastraClient } from "@mastra/client-js";

const client = new MastraClient({
  baseUrl: "http://localhost:15030",
});

const a2a = client.getA2A("analystAgent");
const card = await a2a.getAgentCard();

const stream = a2a.sendMessageStream({
  message: {
    kind: "message",
    role: "user",
    messageId: crypto.randomUUID(),
    parts: [{ kind: "text", text: "What changed around Maharam this week?" }],
  },
});

Mastra subagent

import { A2AAgent } from "@mastra/core/a2a";

export const colophonAnalyst = new A2AAgent({
  url: "http://localhost:15030/.well-known/agent-card.json",
  retries: 2,
  timeoutMs: 30_000,
});
Operating boundary

Use Colophon for source-backed intelligence

Entities, Source Records, signals, claims, assessments, Brand Intelligence Overviews, and explicit evidence gaps.

Do not bypass the contract

Agents should use HTTP, MCP, or A2A. They should not read storage internals, raw vectors, or runtime internals.

Do not treat delegation as promotion

A delegated answer may be useful and cited, but canonical writes still move through reviewed promotion paths.