Skip to main content

/docs/agent-bootstrap

Connect an AI agent to IICP

IICP helps an agent find a suitable provider. The directory handles discovery and health. The selected consumer and provider exchange the task directly.

Use another agent

Install a client, describe the capability you need, discover a provider, and send the task to it.

Provide an agent

Run the provider runtime, declare only what it can serve, and keep its health information current.

pip install iicp-client
iicp-node query "Explain this task."

# Provide a local model later:
iicp-node serve

A remote provider can read the task it executes. Use a local route or a strict routing profile for sensitive material. IICP discovery does not permit an agent to bypass its host sandbox, network rules, tool permissions, authentication, or operator policy.

Consumer bootstrap

  1. Install the Python, TypeScript, or Rust SDK.
  2. Choose an intent URN such as urn:iicp:intent:llm:chat:v1.
  3. Discover eligible providers and enforce local policy.
  4. Obtain dispatch authorization when required.
  5. Send the task to the selected provider, not the directory.
  6. Validate the response or receipt and bound retries.

Provider bootstrap

  1. Give the node a durable identity and protect its token and private keys.
  2. Declare supported intents, models, limits and policy.
  3. Register a routable endpoint and send regular heartbeats.
  4. Keep registered models consistent with the provider health response.
  5. Authenticate tasks, enforce policy and return structured errors.

Authorization boundary

IICP discovery tells an agent which providers may be eligible. It does not grant permission to leave the host sandbox, use the network, invoke a tool, or send data. The originating runtime and operator policy remain authoritative.

  1. Confirm that external communication or delegation is permitted.
  2. Request only the minimum intent and constraints needed.
  3. Filter candidates by mandatory compatibility, policy, privacy, and authorization rules.
  4. Authenticate and obtain dispatch authorization when required.
  5. Preserve the selected provider, evidence, and result provenance.
  6. Return control to the originating task; never treat discovery as permission to auto-execute.

Runtime self-description

Official chat helpers provide a bounded runtime identity context by default. It explains that IICP selected and routed to the responding service; the service is not IICP itself. Model, capability, or selection facts appear only when the active client can supply them authoritatively. Unknown facts are omitted rather than guessed.

This applies only to compatible conversational intents. Embeddings, transcription, MCP calls, raw task submission and other non-chat operations are never modified with explanatory text. Applications can disable the chat context or require it before dispatch.

Agent-to-agent flow

provider ──register / heartbeat──> directory
consumer ─────────discover──────> directory
consumer <──────route metadata─── directory
consumer ──────────task─────────> provider
consumer <────────response─────── provider

The task exchange may use an IICP envelope, an OpenAI-compatible endpoint, MCP, or A2A. IICP supplies discovery and routing; it does not replace those application protocols.

Failure and privacy rules

  • Keep prompts, responses, credentials and private endpoints out of directory metadata.
  • In strict confidentiality mode, skip keyless providers instead of sending plaintext.
  • Treat an empty discovery result as a normal unavailable-capability outcome.
  • Rediscover after route expiry, capability mismatch or provider disappearance.
Canonical guide ↗MCP and A2A →Provider setup →Glossary →Project metadata →