Agent System

What are Agents?

Agents are external services that Arke invokes to process entities. Examples include OCR processors, text summarizers, embedding generators, and classification services.

Agents are registered as entities of type agent and configured with:

• An endpoint URL that Arke calls
• Capabilities declaring what the agent can do
• An API key for authentication
• Permission scoping defining what the agent can access

How Invocation Works

User uploads file
    ↓
Arke queues processing job
    ↓
Arke calls agent endpoint with signed request
    ↓
Agent processes entity, calls back to Arke API
    ↓
Results stored as new entity versions

Request Signing

Arke signs all outbound requests to agents with Ed25519. The signature is included in the X-Arke-Signature header. Agents should verify this signature to ensure requests come from Arke.

The public signing key is available at:

GET /.well-known/signing-key

Temporal Permissions

When Arke invokes an agent, it grants temporary access to the relevant entities. These permissions auto-expire after a configured duration, ensuring agents can't retain access beyond what's needed.

Next Steps

• Building an Agent -- How to build an agent service
• Invoking Agents -- Client-side agent invocation
• Agent Security -- Security model and best practices