OpenA2A/AIM Docs

Agent Management

Register, configure, and manage your AI agents with cryptographic identity verification. Each agent receives a unique Ed25519 key pair for secure authentication and action verification. Monitor agent behavior, manage capabilities, and maintain trust scores from a centralized interface.

📝 API Examples Note: The API examples on this page use https://api.opena2a.org for demonstration. Replace this with your AIM server URL (e.g., http://localhost:8080 for local deployment).

Quick Start: Use the secure() function from the Python SDK for automatic agent registration with zero configuration.

Agent Lifecycle

Registration

Create a new agent with automatic Ed25519 key generation.

POST /v1/agents

Verification

Verify agent identity using cryptographic signatures.

POST /v1/agents/:id/verify

Action Monitoring

Track and verify every action performed by the agent.

POST /v1/agents/:id/verify-action

Credential Rotation

Rotate keys periodically or after security events.

POST /v1/agents/:id/rotate-credentials

Agent Registration

Python SDK (Recommended)

🔍 Auto-Detection: The SDK automatically detects your agent type from Python imports (langchain, crewai, anthropic, openai, etc.). Frameworks take priority over LLM providers.

One-Line Registration (Auto-Detected Type)
from aim_sdk import secure
import langchain  # SDK detects this!

# Register - agent type auto-detected as "langchain"
agent = secure("my-ai-assistant")

# Or specify explicitly:
# from aim_sdk import secure, AgentType
# agent = secure("my-agent", agent_type=AgentType.CREWAI)
Full Registration with Tags & Metadata
from aim_sdk import secure, AgentType

agent = secure(
    "my-ai-assistant",
    agent_type=AgentType.LANGCHAIN,
    capabilities=["db:read", "api:call"],
    mcp_servers=["filesystem", "github"],
    tags=["production", "customer-facing", "support-team"],
    metadata={
        "model": "gpt-4",
        "department": "support",
        "owner": "ai-team@company.com"
    },
    description="Customer support AI agent",
    version="1.0.0"
)

# Force new registration (ignore cached credentials)
agent = secure("my-agent", force_new=True)

Credential Caching: The SDK caches agent credentials locally. Use force_new=True to force a fresh registration (e.g., when updating tags or metadata).

Supported Agent Types

Frameworks (highest priority)

LangChain, LlamaIndex, CrewAI, AutoGen, LangGraph, Haystack, Semantic Kernel

LLM Providers (fallback)

Claude, GPT, Gemini, Llama, Mistral, Cohere

Autonomous Agents

AutoGPT, BabyAGI

Copilots & Assistants

Copilot, Assistant, Chatbot

REST API Registration

Request
curl -X POST https://api.opena2a.org/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-ai-assistant",
    "agentType": "langchain",
    "description": "Customer support AI agent",
    "capabilities": ["text_generation", "sentiment_analysis"],
    "metadata": {
      "model": "gpt-4",
      "version": "1.0.0",
      "department": "support"
    }
  }'

Agent types: claude, gpt, gemini, llama, mistral, cohere, langchain, llamaindex, crewai, autogen, langgraph, haystack, semantic_kernel, copilot, assistant, chatbot, autogpt, babyagi, custom

Response
{
  "id": "agent_2KL9m3nX8fY5pQr7",
  "name": "my-ai-assistant",
  "agentType": "langchain",
  "status": "active",
  "publicKey": "MCowBQYDK2VwAyEA9X2+5GkE5RN0M6VwLjgyH3K...",
  "trustScore": 50.0,
  "createdAt": "2024-01-15T10:30:00Z",
  "capabilities": ["text_generation", "sentiment_analysis"],
  "metadata": {
    "model": "gpt-4",
    "version": "1.0.0",
    "department": "support"
  }
}

Agent Status Management

Status Types

  • activeAgent is operational and can perform actions
  • suspendedTemporarily disabled due to security concerns
  • pendingAwaiting verification or approval
  • terminatedPermanently deactivated

Suspend Agent

Request
curl -X POST https://api.opena2a.org/v1/agents/agent_2KL9m3nX8fY5pQr7/suspend \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Suspicious activity detected",
    "duration_hours": 24
  }'

MCP Server Relationships

Define which MCP (Model Context Protocol) servers your agent communicates with. This creates a "talks_to" relationship for security monitoring and capability mapping.

Add MCP Servers to Agent

Request
curl -X PUT https://api.opena2a.org/v1/agents/agent_2KL9m3nX8fY5pQr7/mcp-servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_server_ids": [
      "mcp_8jK2n4mX9pL3qR5t",
      "mcp_7hJ3m5nY8qM4pS6u"
    ]
  }'

Auto-Detect MCP Servers

Automatically detect and map MCP servers from your agent's configuration file:

Request
curl -X POST https://api.opena2a.org/v1/agents/agent_2KL9m3nX8fY5pQr7/mcp-servers/detect \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem"]
        },
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"]
        }
      }
    }
  }'

Trust Score Management

Every agent has a trust score (0-100) calculated using an 8-factor ML algorithm. Higher trust scores unlock access to more sensitive operations.

Trust Score Factors

  • • Verification History: Success rate of cryptographic verifications
  • • Action Consistency: Predictability and reliability of actions
  • • Security Compliance: Adherence to security policies
  • • Uptime: Operational stability and availability
  • • Error Rate: Frequency of errors and failures
  • • Data Access Patterns: Responsible data handling
  • • API Usage: Rate limit compliance and usage patterns
  • • Peer Reputation: Interactions with other verified agents

Get Agent Trust Score

Request
curl -X GET https://api.opena2a.org/v1/agents/agent_2KL9m3nX8fY5pQr7/trust-score \
  -H "Authorization: Bearer YOUR_TOKEN"

Agent Capabilities

Grant specific capabilities to agents based on their trust score and requirements. Capabilities define what actions an agent is authorized to perform.

Grant Capability

Request
curl -X POST https://api.opena2a.org/v1/agents/agent_2KL9m3nX8fY5pQr7/capabilities \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "db:write",
    "resource": "users_table",
    "constraints": {
      "max_records_per_hour": 1000,
      "allowed_operations": ["INSERT", "UPDATE"],
      "excluded_columns": ["password", "ssn"]
    },
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Agent Tags

Organize agents with tags for easier management and filtering:

Add Tags
curl -X POST https://api.opena2a.org/v1/agents/agent_2KL9m3nX8fY5pQr7/tags \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["production", "customer-facing", "gpt-4", "support-team"]
  }'

Available Endpoints

MethodEndpointDescription
GET/agentsList all agents
POST/agentsCreate new agent
GET/agents/:idGet agent details
PUT/agents/:idUpdate agent
DELETE/agents/:idDelete agent
POST/agents/:id/verifyVerify agent signature
POST/agents/:id/verify-actionVerify and log action
POST/agents/:id/suspendSuspend agent
POST/agents/:id/reactivateReactivate agent
POST/agents/:id/rotate-credentialsRotate keys
GET/agents/:id/sdkDownload SDK
GET/agents/:id/credentialsGet raw keys
GET/agents/:id/mcp-serversList MCP servers
GET/agents/:id/trust-scoreGet trust score
GET/agents/:id/capabilitiesList capabilities
GET/agents/:id/tagsGet agent tags
GET/agents/:id/audit-logsView audit trail
GET/agents/:id/violationsSecurity violations

Next Steps

MCP Servers

Register MCP servers that your agents communicate with.

Trust Scoring

Understand the 8-factor ML algorithm for trust calculation.

Capability Requests

Request additional capabilities for your agents.

REST API Reference

Complete API documentation with all endpoints.