feat(llmobs): add annotateAgentManifest manual API to LLMObs SDK

[yahya-mouman]

Summary

Adds annotateAgentManifest(LLMObs.AgentManifest) to the Java LLMObs SDK, allowing users to manually declare an agent span's configuration (name, instructions, model, model_settings, tools). Mirrors the Python implementation (DataDog/dd-trace-py#19771) and follows the annotatePrompt pattern from #12161.

Changes

• LLMObsTags.java — adds AGENT_MANIFEST = "agent_manifest" constant
• LLMObs.java — adds two public immutable builder classes:
  • LLMObs.AgentTool — represents a single tool (name, optional description, optional parameters)
  • LLMObs.AgentManifest — builder with name, instructions, model, model_settings, tools
• LLMObsSpan.java — adds default void annotateAgentManifest(LLMObs.AgentManifest) (no-op default for backwards compat)
• NoOpLLMObsSpan.java — explicit @Override no-op
• DDLLMObsSpan.java — real implementation: validates span kind (agent only), builds manifest map, stores as _ml_obs_tag.agent_manifest
• LLMObsSpanMapper.java — adds agent_manifest to TAGS_FOR_REMAPPING; serializes to meta.agent_manifest as a msgpack map

Behaviour

LLMObs.AgentManifest manifest = LLMObs.AgentManifest.builder()
    .name("travel_desk")
    .instructions("Book travel for the user.")
    .model("gpt-4o")
    .modelSettings(Map.of("temperature", 0.7))
    .tools(List.of(LLMObs.AgentTool.from("get_weather", "Look up weather", null)))
    .build();

agentSpan.annotateAgentManifest(manifest);

• Only applies to agent span kind; other span kinds emit a log warning and no-op
• Calling twice on the same span overwrites the previous manifest (no merge)
• framework is set to "AgentObs SDK" automatically by the SDK
• name defaults to the span name if not provided
• model_settings keys are forwarded as-is (no allowlist in this initial PR)
• Null manifest is silently ignored

Test plan

• ./gradlew :dd-trace-api:test --tests "datadog.trace.api.llmobs.LLMObsTest" — 27 tests pass (4 new)
• ./gradlew :dd-java-agent:agent-llmobs:test --tests "datadog.trace.llmobs.domain.DDLLMObsSpanTest" — 39 tests pass (7 new)
• ./gradlew :dd-trace-core:test --tests "datadog.trace.llmobs.writer.ddintake.LLMObsSpanMapperTest" — 18 tests pass (2 new)

🤖 Generated with Claude Code

[datadog-prod-us1-6]

🎯 Code Coverage (details)
• Patch Coverage: 82.42%
• Overall Coverage: 58.36% (-0.42%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: b5f56f1 | Docs | View more details | Give us feedback!}

[ncybul]

@codex

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b5f56f11d6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Fall back to the span name for empty manifest names

When a caller supplies .name(""), such as by forwarding an optional configuration value, this selects the empty string instead of the span-name fallback, and the following guard then omits name entirely. The serialized agent manifest is therefore nameless despite the API's default-to-span-name behavior; treat both null and empty names as absent before selecting the fallback.

Useful? React with 👍 / 👎.

[ncybul]

A couple minor suggestions but overall looks good to me! Would be nice to see a manual verification of setting the manifest via the SDK.

[ncybul]

This is different from the Python implementation, right? I think in Python, we were merging the two manifests together whenever possible. It's probably best that we align the implementations and choose one approach.

Personally, I would lean towards merging the fields whenever possible.

[ncybul]

What happens when name is an empty string here?

[ncybul]

Idk if "AgentObs SDK" makes sense here or if we should default to "custom" or "manual" since the former makes it seem like we are determining the agent manifest via the SDK rather than the user supplying it. (same comment applies to the python PR)