a2aproject / a2aproject/a2a-rs

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

オープン
#178 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement
主要言語
Rust
スター
75
フォーク
19
平均マージ
11時間 27分
マージ済み PR(30日)
21

説明

## 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.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
rust
領域
backend-api-design, cli
issue の種類
機能追加
難易度
3/5
見積もり時間
1〜2日
活発さ
活発
明瞭さ
明確に書かれている
初心者へのやさしさ
65/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。