Skip to content

Commit b7c6409

Browse files
terceltercel
committed
docs: Enhance README with official SDK links and multi-language examples, and reorganize documentation specifications into a dedicated spec/ folder.
1 parent 8060257 commit b7c6409

File tree

8 files changed

+95
-59
lines changed

8 files changed

+95
-59
lines changed

‎README.md‎

Lines changed: 83 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,15 @@
1010

1111
**apcore-a2a** is an automatic [A2A (Agent-to-Agent)](https://google.github.io/A2A/) protocol adapter for the [apcore](https://github.com/aipartnerup/apcore-python) ecosystem. It allows you to expose any apcore Module Registry as a fully functional, standards-compliant A2A agent with zero manual effort.
1212

13-
By reading the existing apcore metadata—including `input_schema`, `output_schema`, descriptions, and behavioral annotations—apcore-a2a eliminates the need to hand-write Agent Cards, JSON-RPC endpoints, and task lifecycle logic.
13+
### 🚀 Official SDKs
14+
15+
- **Python SDK**: [aipartnerup/apcore-a2a-python](https://github.com/aipartnerup/apcore-a2a-python)
16+
- **TypeScript SDK**: [aipartnerup/apcore-a2a-typescript](https://github.com/aipartnerup/apcore-a2a-typescript)
1417

1518
---
1619

20+
By reading the existing apcore metadata—including `input_schema`, `output_schema`, descriptions, and behavioral annotations—apcore-a2a eliminates the need to hand-write Agent Cards, JSON-RPC endpoints, and task lifecycle logic.
21+
1722
## Key Features
1823

1924
- **🚀 One-Call Server**: Launch a compliant A2A server using `serve(registry)`.
@@ -29,17 +34,17 @@ By reading the existing apcore metadata—including `input_schema`, `output_sche
2934

3035
## Installation
3136

32-
**Python**
33-
```bash
34-
pip install apcore-a2a
35-
```
36-
Requires Python 3.11+ and apcore 0.9.0+.
37+
=== "Python"
38+
```bash
39+
pip install apcore-a2a
40+
```
41+
*Requires Python 3.11+ and apcore 0.9.0+.*
3742

38-
**TypeScript**
39-
```bash
40-
npm install apcore-a2a
41-
```
42-
Requires Node.js 18+ and apcore-js 0.8.0+.
43+
=== "TypeScript"
44+
```bash
45+
npm install apcore-a2a
46+
```
47+
*Requires Node.js 18+ and apcore-js 0.8.0+.*
4348

4449
---
4550

@@ -49,45 +54,78 @@ Requires Node.js 18+ and apcore-js 0.8.0+.
4954

5055
If you already have apcore modules, you can expose them as an A2A agent in just a few lines:
5156

52-
```python
53-
from apcore import Registry
54-
from apcore_a2a import serve
57+
=== "Python"
58+
```python
59+
from apcore import Registry
60+
from apcore_a2a import serve
5561

56-
# 1. Initialize your registry and discover modules
57-
registry = Registry(extensions_dir="./extensions")
58-
registry.discover()
62+
# 1. Initialize your registry and discover modules
63+
registry = Registry(extensions_dir="./extensions")
64+
registry.discover()
5965

60-
# 2. Start the A2A server
61-
serve(registry, name="My Assistant Agent", host="0.0.0.0", port=8000)
62-
```
66+
# 2. Start the A2A server
67+
serve(registry, name="My Assistant Agent", host="0.0.0.0", port=8000)
68+
```
6369

64-
Your agent is now discoverable at `http://localhost:8000/.well-known/agent.json` (Python) or `/.well-known/agent-card.json` (TypeScript).
70+
=== "TypeScript"
71+
```typescript
72+
import { Registry } from "apcore-js";
73+
import { serve } from "apcore-a2a";
6574

66-
### 2. Call a remote A2A Agent
75+
const registry = new Registry({ extensionsDir: "./extensions" });
76+
await registry.discover();
6777

68-
Use the `A2AClient` to interact with any A2A-compliant agent:
69-
70-
```python
71-
import asyncio
72-
from apcore_a2a import A2AClient
78+
serve(registry, {
79+
name: "My Assistant Agent",
80+
port: 8000,
81+
});
82+
```
7383

74-
async def main():
75-
async with A2AClient("http://remote-agent:8000") as client:
76-
# Discover skills
77-
card = await client.discover()
78-
print(f"Connected to {card['name']} with {len(card['skills'])} skills")
84+
### 2. Call a remote A2A Agent
7985

80-
# Send a message
81-
task = await client.send_message({
82-
"role": "user",
83-
"parts": [{"type": "text", "text": "Hello, how can you help?"}]
84-
}, metadata={"skillId": "general.chat"})
85-
86-
print(f"Task status: {task['status']['state']}")
86+
Use the `A2AClient` to interact with any A2A-compliant agent:
8787

88-
if __name__ == "__main__":
89-
asyncio.run(main())
90-
```
88+
=== "Python"
89+
```python
90+
import asyncio
91+
from apcore_a2a import A2AClient
92+
93+
async def main():
94+
async with A2AClient("http://remote-agent:8000") as client:
95+
# Discover skills
96+
card = await client.discover()
97+
print(f"Connected to {card['name']} with {len(card['skills'])} skills")
98+
99+
# Send a message
100+
task = await client.send_message({
101+
"role": "user",
102+
"parts": [{"type": "text", "text": "Hello, how can you help?"}]
103+
}, metadata={"skillId": "general.chat"})
104+
105+
print(f"Task status: {task['status']['state']}")
106+
107+
if __name__ == "__main__":
108+
asyncio.run(main())
109+
```
110+
111+
=== "TypeScript"
112+
```typescript
113+
import { A2AClient } from "apcore-a2a";
114+
115+
const client = new A2AClient("http://remote-agent:8000");
116+
117+
// Discover skills
118+
const card = await client.discover();
119+
console.log(`Connected to ${card.name}`);
120+
121+
// Send a message
122+
const task = await client.sendMessage(
123+
{ role: "user", parts: [{ type: "text", text: "Hello, how can you help?" }] },
124+
{ metadata: { skillId: "general.chat" } }
125+
);
126+
127+
console.log(`Task status: ${task.status.state}`);
128+
```
91129

92130
---
93131

@@ -107,12 +145,10 @@ apcore-a2a acts as a thin, protocol-specific layer on top of `apcore-python`. It
107145

108146
## Documentation
109147

110-
- **[Getting Started Guide](docs/getting-started.md)** — Install, serve, and call agents (Python & TypeScript)
148+
- **[Full Documentation Site](https://aipartnerup.github.io/apcore-a2a/)**
149+
- **[Getting Started Guide](docs/getting-started.md)** — Install, serve, and call agents
111150
- [Feature Specs Overview](docs/features/overview.md) — All feature specifications
112-
- [Product Requirements (PRD)](docs/prd.md)
113-
- [Technical Design (TDD)](docs/tech-design.md)
114-
- [Software Requirements (SRS)](docs/srs.md)
115-
- [Test Plan](docs/test-plan.md)
151+
- [Specifications (PRD, TDD, SRS)](docs/spec/)
116152

117153
---
118154

‎docs/features/overview.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ client ────────────────────────
3232

3333
## Related Documents
3434

35-
- [Getting Started](../getting-started.md) — Installation & usage guide (Python & TypeScript)
36-
- [PRD](../prd.md) — Product Requirements Document
37-
- [SRS](../srs.md) — Software Requirements Specification
38-
- [Tech Design](../tech-design.md) — Technical Design Document
39-
- [Test Plan](../test-plan.md) — Test Plan
35+
- [Getting Started](../getting-started.md) — Installation & usage guide
36+
- [Product Requirements (PRD)](../spec/prd.md)
37+
- [Technical Design](../spec/tech-design.md)
38+
- [Software Requirements (SRS)](../spec/srs.md)
39+
- [Test Plan](../spec/test-plan.md)

‎docs/getting-started.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -366,5 +366,5 @@ Get the underlying app object and mount it into your existing web framework.
366366
- **Push Notifications**: Enable `push_notifications=True` for webhook-based async task updates
367367
- **Multi-Agent Workflows**: Use `A2AClient` to orchestrate multiple agents in complex pipelines
368368
- **Custom Storage**: Implement the `TaskStore` protocol for Redis/PostgreSQL persistence
369-
- **Detailed Design**: See the [Tech Design](tech-design.md) for architecture deep-dive
370-
- **Feature Specs**: See [docs/features/](features/overview.md) for implementation details
369+
- **Detailed Design**: See the [Technical Design](spec/tech-design.md) for an architecture deep-dive.
370+
- **Feature Specs**: See the [Feature Specs Overview](features/overview.md) for implementation details.

docs/prd.md renamed to docs/spec/prd.md

File renamed without changes.

docs/srs.md renamed to docs/spec/srs.md

File renamed without changes.

docs/tech-design.md renamed to docs/spec/tech-design.md

File renamed without changes.

docs/test-plan.md renamed to docs/spec/test-plan.md

File renamed without changes.

‎mkdocs.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,6 @@ nav:
2929
- Home: index.md
3030
- Getting Started: getting-started.md
3131
- Changelog: changelog.md
32-
- Specifications:
33-
- Product Requirements (PRD): prd.md
34-
- Technical Design: tech-design.md
35-
- Software Requirements (SRS): srs.md
36-
- Test Plan: test-plan.md
3732
- Features:
3833
- Overview: features/overview.md
3934
- Adapters: features/adapters.md
@@ -47,6 +42,11 @@ nav:
4742
- CLI: features/cli.md
4843
- Explorer: features/explorer.md
4944
- Ops: features/ops.md
45+
- Specifications:
46+
- Product Requirements (PRD): spec/prd.md
47+
- Technical Design: spec/tech-design.md
48+
- Software Requirements (SRS): spec/srs.md
49+
- Test Plan: spec/test-plan.md
5050

5151
markdown_extensions:
5252
- tables

0 commit comments

Comments
 (0)