Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Agent Author Guide

CRAFT is a multi-agent platform built on the A2A protocol. Every capability in CRAFT — from natural-language SQL generation to semiconductor yield analysis — runs as a discrete, independently deployable agent. The short version: CRAFT gives you managed LLMs, tool discovery, and an agent registry. Your agent gets all three by pointing its LLM client at the CRAFT gateway and making one API call to register. Start with the tutorial if you want to be running in under 20 minutes. This overview covers what it means to be an agent on CRAFT, when to build one, how to choose a framework, and how the platform integrates with your agent at runtime.

​
What is an agent on CRAFT?

A CRAFT agent is a service that:
  1. Exposes an Agent Card at /.well-known/agent-card.json describing its identity, skills, and capabilities
  2. Accepts work via A2A JSON-RPC (message/send or message/stream)
  3. Streams progress and results back as SSE events
  4. Registers with the Assets API so other agents and the orchestrator can discover and invoke it
Agents are microservices first. They can be authored in any language, deployed anywhere, and call any tools — as long as they speak the A2A protocol at their boundary.

​
When should you build an agent?

  • You have a bounded capability with a clear input/output contract (e.g., “turn natural language into SQL”, “generate yield analysis charts”)
  • The capability needs to be independently scalable or deployable
  • The capability will be invoked by other agents or orchestrators
  • You want the capability to appear in the platform’s agent registry and be discoverable by the orchestrator
  • The capability is owned by a separate team with its own release cadence
  • The capability is a simple function call used only within a single agent — add it as a tool instead
  • The capability is a data transformation pipeline with no LLM reasoning — use a standard service
  • You need real-time collaboration between multiple LLMs sharing memory — use sub-agents within the same ADK process
  • The capability is a UI-layer concern — use CRAFT’s REST API directly

​
Framework choice

CRAFT supports four agent frameworks. Choose based on your team’s constraints and the nature of your agent.
FrameworkLanguageBest ForProsCons
Google ADKPythonAnalytics, multi-agent orchestration, data pipelinesNative A2A (to_a2a()), RemoteA2aAgent for sub-agent delegation, model-agnostic via LiteLLM, ADK Web for debuggingA2A support still experimental; Python-only
Claude Agent SDKPython, TypeScriptReasoning-heavy tasks, document analysis, complex multi-step workflowsExtended thinking, strong tool-use, multi-turn conversation handlingNo native A2A server — wrap with a2a library manually
Pydantic AIPythonType-safe agents, data-structured outputs, MCP toolsetsFastMCPToolset for MCP integration, strict typing, clean dependency injection via deps_typeLess mature ecosystem than ADK
LangGraphPythonStateful workflows, graph-based logic, conditional branchingExplicit state machine, fine-grained control over execution flowMore boilerplate; no native A2A — wrap with a2a library
CrewAI and role-based frameworks are not supported on CRAFT. Multi-agent coordination on CRAFT happens at the protocol layer through A2A — agents discover each other via the registry and communicate via JSON-RPC. Role-based crew frameworks duplicate this coordination mechanism and create tight coupling that breaks independent deployability. Do not use them.

​
Framework decision flowchart

​
Platform integration points

Every agent on CRAFT integrates with three platform services at runtime.

​
Assets API — agent registry

The Assets API is the source of truth for agent discovery. Before your agent can be invoked by an orchestrator, you must register it: 
curl -X POST "https://<platform-host>:8002/assets/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-ID: <your-project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_card": { ... },
    "tags": ["analytics"],
    "visibility": "TENANT_ONLY"
  }'
The registry stores the Agent Card, assigns a resource_uri (agent:<org>:<project>:<name>), and makes the agent discoverable to orchestrators and other platform consumers.

​
LiteLLM gateway — model access

All LLM calls from agents on CRAFT route through the shared LiteLLM gateway. This provides:
  • Unified model access — use Gemini, Claude, GPT-4o, and others with a single OpenAI-compatible endpoint
  • Cost tracking — per-org, per-project token usage recorded automatically
  • Rate limiting — enforced per tenant to prevent runaway costs
  • Model aliasing — LLM_PRO, LLM_LIGHT constants resolve to the current best model for each tier
Configure your agent to point at the gateway: 
# Google ADK — via LiteLLM model string
root_agent = Agent(
    model="litellm/gemini-2.0-flash",  # gateway resolves the alias
    ...
)

# Pydantic AI — via GoogleProvider with gateway URL
provider = GoogleProvider(api_key=settings.google_api_key)
model = GoogleModel(LLM_PRO.split("/")[1], provider=provider)

​
em-runtime-mcp — tool access

CRAFT agents access data and platform capabilities through the em-runtime-mcp MCP server. Tools available include database schema inspection, query execution, artifact upload/download, and context graph queries. 
# Pydantic AI — FastMCPToolset connects to em-runtime-mcp
from pydantic_ai.toolsets.fastmcp import FastMCPToolset
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

mcp_client = Client(
    transport=StreamableHttpTransport(settings.mcp_server_url),
)
toolset = FastMCPToolset(mcp_client)
Create a fresh MCP client and toolset per agent request. Do not reuse a single long-lived client across requests — MCP sessions can expire or the MCP server pod can restart.

​
Guide contents

A2A Protocol Primer

Agent Cards, JSON-RPC methods, SSE streaming, and the task lifecycle.

Your First Agent

Framework-by-framework tutorial: Google ADK, Claude Agent SDK, Pydantic AI, LangGraph.

Tool Authoring

Function tools, MCP tools via FastMCPToolset, schema discipline.

Multi-Agent Patterns

Delegation, supervision, and parallel fan-out via A2A.

Streaming Idioms

SSE streaming, partial results, cooperative cancellation.

Eval Harness

Langfuse evaluators, regression suites, golden traces.

Debugging Agents

Trace inspection, prompt iteration, common failure modes.