Skip to content

Prompt Resources And Context

pydantic-acp supports ACP prompt content beyond plain text.

That matters most in editor and coding-agent integrations where the client wants to attach:

  • selected file ranges
  • branch diffs
  • file references
  • directory references
  • image inputs
  • audio inputs
  • embedded text or binary resources

The adapter treats these as prompt input, not as hidden tool calls.

What The Adapter Supports

pydantic-acp currently accepts these ACP prompt block families:

  • TextContentBlock
  • ResourceContentBlock
  • EmbeddedResourceContentBlock
  • ImageContentBlock
  • AudioContentBlock

Execution behavior is intentionally simple:

  • plain text stays plain text
  • resource links stay references
  • embedded text resources become explicit context blocks
  • image and audio blocks become binary prompt parts
  • embedded binary resources become binary prompt parts

The adapter does not turn an attached resource into an automatic tool invocation.

If a client attaches a branch diff or a file selection, the model receives that diff or selection as context. The adapter does not run git diff, reopen the file, or fetch the resource again just because the prompt referenced it.

Text Rules Are Just Text

Prompts such as:

@rule write concise code

are treated as normal text content unless your own runtime adds additional meaning.

pydantic-acp does not define a special ACP primitive for @rule. That is deliberate:

  • plain textual rules should survive as-is
  • the adapter should not invent custom runtime semantics the source agent does not actually expose

ACP resource links are the lightweight reference form.

Typical examples:

[@acpkit](file:///workspace/acpkit)

[@README.md](file:///workspace/acpkit/README.md)

In ACP terms this is a ResourceContentBlock.

pydantic-acp behavior:

  • text-like links stay text links
  • image links become ImageUrl
  • audio links become AudioUrl
  • other typed links become DocumentUrl

This means a client can attach a file or directory reference without embedding the whole payload.

Embedded Text Context

The higher-value path for editor integrations is embedded text context.

That is how a client can attach a selected range, file snippet, or generated diff directly into the prompt so the agent does not need another round trip to inspect it.

pydantic-acp renders embedded text resources in this form:

[@_hook_capability.py?symbol=wrap_run#L79:79](file:///workspace/acpkit/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/_hook_capability.py?symbol=wrap_run#L79:79)
<context ref="file:///workspace/acpkit/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/_hook_capability.py?symbol=wrap_run#L79:79">
    async def wrap_run(
</context>

This is the important contract:

  • the URI stays visible
  • the attached text stays visible
  • the model sees one explicit context block, not an opaque placeholder

That makes selections, excerpts, and diffs reviewable and replayable.

Zed Selections And Branch Diffs

Zed-style attachments fit naturally into the embedded-text-resource path.

Examples:

[@git-diff?base=main](zed:///agent/git-diff?base=main)
<context ref="zed:///agent/git-diff?base=main">
diff --git a/app.py b/app.py
@@ -1 +1 @@
-old
+new
</context>

[@thread_executor.py#L54:54](file:///workspace/acpkit/references/pydantic-ai-latest/pydantic_ai_slim/pydantic_ai/capabilities/thread_executor.py#L54:54)
<context ref="file:///workspace/acpkit/references/pydantic-ai-latest/pydantic_ai_slim/pydantic_ai/capabilities/thread_executor.py#L54:54">
executor
</context>

This is useful in Zed because the editor can attach:

  • a branch diff
  • a symbol selection
  • a selected range
  • a file snippet

without requiring the agent to reopen the same context through tools.

The adapter preserves these as prompt context and advertises embedded_context=True in ACP prompt capabilities.

Images, Audio, And Embedded Binary Resources

pydantic-acp now also carries binary prompt input into pydantic-ai instead of flattening everything to placeholder text.

Current behavior:

  • ImageContentBlock -> BinaryContent
  • AudioContentBlock -> BinaryContent
  • embedded blob resources -> BinaryContent

That means the ACP boundary can now preserve real binary prompt input when the downstream model provider supports it.

Important limit:

  • the adapter can carry the input faithfully
  • the provider still decides whether the selected model actually supports image, audio, or document-style inputs

File And Directory References

ACP does not need a separate "directory prompt primitive" for common editor workflows.

A directory reference such as:

[@acpkit](file:///workspace/acpkit)

is just a resource link.

Use a resource link when:

  • you want to point at a file or directory
  • you do not want to inline the full content

Use an embedded text resource when:

  • you want the model to see exact attached text immediately
  • you want to include a selection, snippet, or generated diff

What This Does Not Do

This resource support is intentionally prompt-oriented.

It does not:

  • automatically execute a command because a branch diff was attached
  • reopen a file because a file URI was present
  • infer tool calls from directory links
  • invent ACP semantics that do not exist in the source runtime

If your agent should inspect the live workspace again, that still happens through normal tools or host-backed capabilities. Attached resources are just prompt context.

For ACP clients and editor integrations:

  • send plain instructions as text blocks
  • send lightweight file or directory pointers as resource links
  • send selected ranges, branch diffs, or excerpts as embedded text resources
  • send image and audio input only when the target model path can make use of it

For Zed-style integrations specifically:

  • use embedded text resources for branch diffs and selected ranges
  • keep the source URI intact
  • prefer attached context over forcing the model to rediscover the same content through tools

Current Guarantees

The adapter currently guarantees:

  • ACP prompt capabilities advertise image, audio, and embedded_context
  • text-only prompts still stay simple strings
  • mixed prompts become pydantic-ai user-content lists
  • embedded text context preserves the context ref wrapper
  • file and directory links survive as links
  • Zed branch diff and selection-style URIs are preserved

That makes prompt attachments practical for editor clients without turning them into a parallel tool system.