Skip to content

docs: post-#252 reconciliation for azure_ai/agents/<id> (init prompt + targets docs) [blocked on #253] - #256

Draft
tangym wants to merge 2 commits into
mainfrom
docs/foundry-agent-init-coverage
Draft

docs: post-#252 reconciliation for azure_ai/agents/<id> (init prompt + targets docs) [blocked on #253]#256
tangym wants to merge 2 commits into
mainfrom
docs/foundry-agent-init-coverage

Conversation

@tangym

@tangym tangym commented Jun 26, 2026

Copy link
Copy Markdown
Collaborator

Summary

Reconciles the assert-ai init system prompt and the user-facing target docs with the azure_ai/agents/<AGENT_ID> Foundry hosted-agent route that #252 added.

Splits cleanly into two commits so the safe part can ship independently if needed:

  1. docs(prompts): teach assert-ai init about azure_ai/agents/<id> — Parse-error prevention. The TargetConfig parser rejects target.tools and target.system_prompt when the model name starts with azure_ai/agents/, but the init system prompt did not learn this rule, so assert-ai init currently proposes configs that fail at parse time when a user describes a Foundry agent. v1/v2-agnostic — would be correct to ship today.

  2. docs(targets): document Foundry hosted-agent target [BLOCKED on #253] — Promotes the Foundry route in docs/targets/README.md (decision-tree + "paths at a glance" tables) and adds a "Foundry hosted agent target" subsection to docs/targets/model-and-tools.md. Held until feat(targets): add native target for Azure AI Foundry v2 Agents (UUID IDs) #253 ships full Foundry v2 agent support. PR feat(azure-auth): native AAD support for azure_ai/* targets (Foundry hosted agents) #252 only covers v1, and the v2 path still needs a workaround, so promoting the route in public target docs now would oversell coverage.

Why draft?

Bidirectional pickup for #253:

When #253 lands, the v2 implementer should:

  1. Rebase this branch.
  2. Adjust commit 2's wording if needed (e.g. cover both v1 and v2 ID shapes).
  3. Flip the PR to ready for review.

If we want commit 1 sooner, it can be cherry-picked into a tiny standalone ship-now PR without losing the draft.

Verification

  • Re-read the updated decision tree end-to-end as if I were the init LLM, with two synthetic inputs:
    1. "I have a LangGraph agent in src/my_agent/bot.py" → routes to callable. ✓
    2. "I have a Foundry agent, agent ID asst_abc123" → routes to model sub-case 2b; does not ask for system_prompt/tools. ✓
  • python3 -m compileall -q assert_ai (no code changed; sanity check).

Files

File Commit
assert_ai/internal_pipeline_prompts/init_system.md 1
docs/targets/README.md 2 (blocked)
docs/targets/model-and-tools.md 2 (blocked)

Related: #252, #253

tangym added 2 commits June 26, 2026 01:05
PR #252 added the azure_ai/agents/<AGENT_ID> target route for hosted
Foundry agents and rejects target.tools / target.system_prompt for it
at parse time. The auth surfaces (docs/getting-started.md,
docs/config/schema.md) were updated, but the assert-ai init system
prompt did not learn about the new route, so init currently proposes
configs that fail at parse time when a user describes a Foundry agent.

- Split the 'model' decision-tree branch into 2a (hosted chat model)
  and 2b (Foundry hosted agent).
- Forbid target.system_prompt and target.tools in the 2b sub-case to
  match the TargetConfig parser rejection.
- Tighten the Target-Type propose-readiness check.
- Note the azure_ai/agents/* sub-case in the inference YAML skeleton
  and in the customization hints.

Parse-error prevention; no v1/v2 functional dependency.
Add the azure_ai/agents/<AGENT_ID> route to the user-facing target
docs: a row in the decision tree and 'paths at a glance' tables in
docs/targets/README.md, plus a new 'Foundry hosted agent target'
subsection in docs/targets/model-and-tools.md with a runnable YAML
snippet and auth requirements.

This commit is intentionally HELD until #253 ships full Foundry v2
agent support (UUID IDs). PR #252 only covers v1 agents, and the
v2 path still requires a workaround, so promoting this route in
public target docs now would oversell coverage.

When #253 lands, rebase this commit on top, drop or amend as needed
(e.g. tweak wording to cover both v1 and v2), and flip the PR to
ready for review.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant