a2aproject / a2aproject/a2a-rs

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

Open
#178 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Rust
Stars
75
Forks
19
Avg merge
11h 27m
Merged PRs (30d)
21

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.