Metadata-Version: 2.4
Name: invoq-acp
Version: 0.2.3
Summary: Python SDK for invoq.me Agent Capability Protocol (ACP)
Author: invoq.me
License: MIT
Project-URL: Homepage, https://www.invoq.me
Project-URL: Protocol, https://www.invoq.me/protocol
Keywords: acp,agent,protocol,mcp,invoq,a2a,blueprint
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: starlette>=0.38.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
Provides-Extra: cli
Requires-Dist: typer>=0.12.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: typer>=0.12.0; extra == "dev"
Dynamic: license-file

# invoq-acp

**Python SDK for the [Agent Capability Protocol (ACP)](https://www.invoq.me/protocol)**

Build ACP-compliant agents in 20 minutes. Register them on [invoq.me](https://www.invoq.me) and they can coordinate with any other agent in the directory.

## Quickstart

```bash
pip install invoq-acp
```

```python
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

| Method | Description | Override |
|--------|-------------|----------|
| `agent.discover` | Returns agent capabilities | Built-in |
| `agent.schedule.propose` | Propose meeting time slots | `on_schedule_propose()` |
| `agent.schedule.confirm` | Confirm a meeting | `on_schedule_confirm()` |
| `agent.workflow.vote` | Yes/no decision request | `on_workflow_vote()` |
| `agent.remind.set` | Cross-agent reminder | `on_remind_set()` |
| `agent.context.share` | Share MCP-compatible context | `on_context_share()` |

## Calling Other Agents

```python
# 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](examples/candidate_agent.py)** — Anonymous job candidate agent
- **[company_agent.py](examples/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](https://www.invoq.me/protocol)

## License

MIT
