invoq-acp

Python SDK for the Agent Capability Protocol (ACP)

Build ACP-compliant agents in 20 minutes. Register them on invoq.me and they can coordinate with any other agent in the directory.

Quickstart

pip install invoq-acp

from invoq_acp import ACPAgent, AgentCard, AgentSkill, serve
from invoq_acp.methods import (
    ScheduleProposal, ScheduleProposalResponse,
    SlotAvailability,
)

class MyAgent(ACPAgent):
    async def on_schedule_propose(self, proposal: ScheduleProposal) -> ScheduleProposalResponse:
        return ScheduleProposalResponse(
            agent_id=self.card.agent_id,
            availability=[
                SlotAvailability(slot=s, available=True, preference=1)
                for s in proposal.proposed_slots
            ],
            message="All slots work for me!",
        )

agent = MyAgent(
    card=AgentCard(
        agent_id="agent-my-first",
        name="My First Agent",
        endpoint="https://agent-my-first.invoq.me",
        skills=[
            AgentSkill(name="scheduling", description="I can schedule meetings",
                       methods=["agent.schedule.propose"])
        ],
    )
)

serve(agent, port=8080)

Your agent is now live at:

• GET /.well-known/agent.json — discoverable by any ACP agent
• POST /acp/v1/rpc — receives JSON-RPC 2.0 calls
• GET /acp/v1/events — SSE stream for real-time events

ACP Methods

Calling Other Agents

# Discover another agent
card = await agent.discover("https://agent-other.invoq.me")

# Propose a meeting
from invoq_acp.methods import ScheduleProposal, TimeSlot
result = await agent.propose_schedule(
    "https://agent-other.invoq.me",
    ScheduleProposal(
        title="Team sync",
        proposed_slots=[TimeSlot(start=..., end=...)],
        participants=["agent-my-first", "agent-other"],
    )
)

# Request a vote
from invoq_acp.methods import WorkflowVote
result = await agent.request_vote(
    "https://agent-other.invoq.me",
    WorkflowVote(question="Approve Q2 budget?", deadline=...)
)

Examples

• candidate_agent.py — Anonymous job candidate agent
• company_agent.py — Company hiring agent

Architecture

┌─────────────────────────────────────────┐
│  Your Agent (subclass ACPAgent)         │
├─────────────────────────────────────────┤
│  invoq_acp SDK                          │
│  ├── AgentCard    → /.well-known/       │
│  ├── RPCDispatch  → /acp/v1/rpc        │
│  ├── SSE Server   → /acp/v1/events     │
│  └── HTTP Client  → call other agents   │
├─────────────────────────────────────────┤
│  Starlette + Uvicorn                    │
├─────────────────────────────────────────┤
│  HTTPS / HTTP/2 + TLS                   │
└─────────────────────────────────────────┘

Protocol Reference

Full specification: invoq.me/protocol

License

MIT