Genai utils | Add AgentInvocation type

[etserend]

Description

This PR adds the AgentInvocation type extending _BaseAgent for agent invocation (invoke_agent) spans. It provides TelemetryHandler lifecycle methods and an agent() context manager — aligned with the GenAI agent span semantic conventions.

Builds on the _BaseAgent base class and AgentCreation type added in #4217. Agent metrics and events to come in follow-up PRs.

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• Basic unit tests for starting and stopping agent invocation spans
• Unit tests for agent invocation with all attributes (request + response)
• Unit tests for context manager happy path and error path
• Unit tests for AgentInvocation dataclass defaults and messages

Does This PR Require a Core Repo Change?

• No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated

[etserend]

Sample trace from [demo app](Trace: b6db19ce1c2846667d1b237c4e264a0a

Trace: b6db19ce1c2846667d1b237c4e264a0a

invoke_agent Poet Agent (1.970s, Client)
├── gen_ai.operation.name: invoke_agent
├── gen_ai.agent.name: Poet Agent
├── gen_ai.agent.description: Writes short poems
├── gen_ai.provider.name: openai
├── gen_ai.request.model: gpt-4o-mini
├── gen_ai.response.model: gpt-4o-mini-2024-07-18
├── gen_ai.response.id: chatcmpl-DF5wUAWLGG75qrEFwE5QKlB40QA85
├── gen_ai.usage.input_tokens: 15
├── gen_ai.usage.output_tokens: 19
├── server.address: api.openai.com
├── server.port: 443
│
└── chat gpt-4o-mini (1.950s, Client)
    ├── gen_ai.operation.name: chat
    ├── gen_ai.request.model: gpt-4o-mini
    ├── gen_ai.response.model: gpt-4o-mini-2024-07-18
    ├── gen_ai.response.id: chatcmpl-DF5wUAWLGG75qrEFwE5QKlB40QA85
    ├── gen_ai.system: openai
    ├── gen_ai.usage.input_tokens: 15
    ├── gen_ai.usage.output_tokens: 19
    └── server.address: api.openai.com

[keith-decker]

I'm starting to see a lot of duplicated properties on types. Wondering if we can consolidate some of these into reusable bits.

[keith-decker]

This can probably be a helper to be used with agent/llm/tool invocations