feat: agents apis

[Thijs van der Velden (tve-corti)]

Summary

This pull request adds two new helper methods to the SDK to improve developer experience when working with agent cards and authentication headers.

Changes

1. Add agents.getCardUrl() method

Introduces a new helper method getCardUrl(agentId: string): Promise<URL> to the agents client that constructs the URL for retrieving an agent's card JSON file. The method automatically resolves the correct environment-specific base URL and builds the path /agents/{agentId}/agent-card.json.

Implementation:

• Creates new CustomAgents class extending the auto-generated AgentsClient
• Integrates custom agents client into CortiClient

Test coverage: Unit tests for various agent IDs, environments (eu, us, dev-eu), authentication methods (client credentials, bearer token), and URL encoding edge cases.

2. Add getAuthHeaders() method

Adds a new public method getAuthHeaders(): Promise<Headers> to CortiClient that returns a Headers object containing the Authorization header with the current access token and the Tenant-Name header. This simplifies header construction for developers making custom API requests.

Implementation:

• Retrieves authentication request from the configured auth provider
• Combines Authorization header with tenant name from client options

Test coverage: Comprehensive tests covering client credentials, bearer tokens, async token retrieval, error propagation, and header structure validation.

Files Modified

• CortiClient.ts
• CustomAgents.ts (new)
• agents.getCardUrl.integration.ts (new)
• cortiClient.getAuthHeaders.integration.ts (new)

[Copilot]

Pull request overview

This PR improves the SDK developer experience by adding (1) a helper for constructing the agent-card URL and (2) a helper for generating auth-related headers for custom requests.

Changes:

• Added agents.getCardUrl(agentId) on a custom Agents client to construct /agents/{agentId}/agent-card.json against the environment-specific agents base URL.
• Added CortiClient.getAuthHeaders() to return a Headers object containing Authorization and Tenant-Name.
• Added unit tests covering these helpers across auth/environment scenarios.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
src/custom/CortiClient.ts	Integrates CustomAgents into CortiClient and adds getAuthHeaders() helper.
src/custom/agents/CustomAgents.ts	Introduces CustomAgents extending the generated AgentsClient and adds getCardUrl().
tests/custom/agents.getCardUrl.test.ts	Adds tests for the new agents.getCardUrl() helper.
tests/custom/cortiClient.getAuthHeaders.test.ts	Adds tests for the new CortiClient.getAuthHeaders() helper.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Natalia Markitantova (markitosha)]

LGTM 👍
Only one comment about comment 😅 (and you have to fix linter anyway)
Ping me if you need instructions how to "release" a version (I believe I didn't update docs yet)!