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)

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.