a2aproject / a2aproject/a2a-rs

a2acli: Agent Card reference resolution (--agent-card) and direct --endpoint

Đang mở
#178 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
enhancement
Ngôn ngữ chính
Rust
Star
75
Fork
19
Merge trung bình
11 giờ 27 phút
Pull request đã merge (30 ngày)
21

Mô tả

## Summary

`SPEC.md` §10.1 (`A2ACLI_CARD_GET_001`, Tier 1 MUST) requires the agent to be named by an **Agent Card reference** given to `-a/--agent-card`, in any of three forms:

- a bare host or origin — the well-known path `/.well-known/agent-card.json` is appended;
- a full card URL — used as-is;
- a local file path — `file://…` or a plain filesystem path.

`a2acli` today has none of these. It exposes `--base-url` (`a2acli/src/lib.rs`), which only handles the bare-origin case:

```rust
let url = format!("{}/.well-known/agent-card.json", cli.base_url.trim_end_matches('/'));
```

`--base-url` is not a flag the specification defines at all. The canonical Go implementation has both spec flags:

```go
pf.VarP(&cfg.agentCard, "agent-card", "a", "Agent Card reference: host/origin, full card URL, or local file path")
pf.StringVarP(&cfg.url, "endpoint", "e", "", "Agent interface URL for a direct connection; skips card resolution and requires a single --transport flag")
```

with the three-form normalization in `internal/flagparse/urlorpath.go`.

## Why

A script written against the standard surface cannot point `a2acli` at a card URL or a local card file, and cannot connect directly to an interface URL. It is also the one remaining case where `a2acli`'s global flags diverge from both the specification and the reference implementation, so `--agent-card` appearing in any shared example or Agent Skill silently fails here.

Resolving a card from a local file is not a convenience: it is how the tool is driven in tests and air-gapped environments without standing up an agent.

## Scope

- [ ] Add `-a/--agent-card ` (env `A2ACLI_AGENT_CARD`) accepting all three reference forms, normalizing to a URL with an explicit scheme; model on `internal/flagparse/urlorpath.go`.
- [ ] Read a `file://` or plain-path reference from disk rather than over HTTP, and parse it as an `AgentCard`.
- [ ] Add `-e/--endpoint ` (env `A2ACLI_ENDPOINT`) to connect directly to an interface URL, skipping card resolution. Per §7.2 it MUST be used with exactly one `--transport`; reject any other combination as a usage error (exit 2).
- [ ] Keep `--base-url` working as a **hidden** alias for the bare-origin form, so existing scripts and this repo's own examples do not break. Not documented; the canonical flag is `--agent-card`.
- [ ] Classify a local-file failure per Appendix D: unreadable/absent file is `A2ACLI_ERR_CARD_NOT_FOUND`, a file that is not a valid card is `A2ACLI_ERR_CARD_INVALID`.
- [ ] `config show` reports `agent_card` and `endpoint` with their resolved sources.
- [ ] Update `a2acli/README.md` and the root `README.md` to lead with `--agent-card`.

## Requirements closed

| ID | Requirement |
| --- | --- |
| `A2ACLI_CARD_GET_001` | `card get` — resolve and parse an Agent Card from a host, an explicit URL, or a `file://` path, and use it to select a transport (§10.1, §13) |

## Notes

This is the only Tier 1 item that changes an existing flag's status, hence the hidden-alias approach. Filed alongside #164's other residuals; blocked on #177 merging.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Start in a2acli/src/lib.rs where --base-url is currently handled. Look at the Go reference implementation in internal/flagparse/urlorpath.go for the three-form normalization logic. The work involves adding new flags, reading from files, and parsing AgentCard JSON. Run existing tests to ensure the hidden alias --base-url still works, and update the README files.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
rust
Lĩnh vực
backend-api-design, cli
Loại issue
Tính năng
Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
65/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.