Feature: ACP SDK

[EmilienM]

🚀 Feature Description

Is your feature request related to a problem?
Currently, interacting with the Ambient Platform requires manual operation via the Web UI or constructing raw HTTP requests to the Go/Gin backend. This makes it difficult to integrate agentic sessions into automated workflows, CI/CD pipelines, or external applications. Developers have to manually manage authentication headers and parse raw JSON responses, which is brittle and error-prone.

Describe the solution you'd like
I would like a dedicated Client SDK (starting with Python) that wraps the platform's REST API. This SDK should provide a strongly-typed, programmatic interface to create, monitor, and interact with agentic sessions without needing to understand the underlying Kubernetes Custom Resource definitions or API routes.

💡 Proposed Solution

Detailed Description:
The SDK should serve as a lightweight wrapper around the existing backend API. It needs to handle:

1. Configuration: Automatic loading of credentials (e.g., AMBIENT_API_KEY or kubeconfig context).
2. Session Management: Methods to create_session, get_session_status, and list_sessions.
3. Real-time Updates: A mechanism (polling or WebSocket wrapper) to stream agent logs and status changes.

User Experience:
A developer should be able to spin up an agent to review code or run a task with just a few lines of code:

from ambient_platform import Client

client = Client.from_env()

# Start a new agentic session
session = client.sessions.create(
    task="Review PR #123 for security vulnerabilities",
    model="claude-4-5-sonnet",
    context={"repo": "my-org/my-repo"}
)

# Wait for completion and print result
result = session.wait_for_completion()
print(result.artifacts)

🎯 Use Cases

Primary Use Case:
DevOps engineers and Developers who want to chain Ambient agents into larger automation pipelines (e.g., triggering a "Security Review Agent" automatically when a GitHub Actions workflow fails).

User Stories:

• As a Platform Engineer, I want to trigger agentic sessions via a Python script so that I can schedule nightly code audits.
• As a Developer, I want to fetch the results of previous sessions programmatically so that I can generate custom reports on agent performance.

🔧 Technical Considerations

Component: [vTeam Tools / Infrastructure]

Implementation Approach:

1. Code Generation: Consider using OpenAPI Generator if the Go backend has Swagger/OpenAPI specs available.
2. Manual Wrapper: If no spec exists, build a manual requests-based wrapper ensuring robust error handling (retries, timeouts).
3. Typing: Use Pydantic models for request/response bodies to ensure type safety for the user.

Dependencies:

• We need a frontend rest API endpoint which we don't have right now.

Breaking Changes:
None. This is an additive feature layer on top of the existing API.

📊 Success Metrics

How will we measure the success of this feature?

• Metric 1: Integration Usage (Number of API calls originating from the SDK User-Agent vs. Web UI).
• User feedback: Qualitative feedback from the community on ease of automation.

🔄 Alternatives Considered

Alternative 1: CLI Tool Only
We could just improve the CLI, but that makes programmatic integration (e.g., inside a Python web server) clumsy as it requires shelling out.

Alternative 2: Direct REST API Documentation
We could just document the API better (Swagger UI), but this still places the burden of authentication and type checking on the user.

Do nothing:
Users will continue to build "hacky" bash scripts to curl the API, leading to a fragmented ecosystem and higher support burden when API versions change.

📋 Additional Context

Screenshots/Mockups:
N/A (Code-based feature)

Related Issues:

• Link to any existing issues regarding API exposure or CLI improvements.

External References:

• Reference: [OpenAI Python Library](https://github.com/openai/openai-python) (Standard for ease of use in AI tools).

✅ Acceptance Criteria

• SDK repository or folder initialized.
• Authentication flow (API Key / Auth Token) implemented.
• CRUD methods implemented for Sessions.
• Example script provided in examples/.
• Published to PyPI (or internal registry).

🏷️ Labels

• Priority: medium
• Effort: M
• Component: tools
• Type: new-feature

[markturansky]

There are many components in Ambient that share the same data model. Is this SDK meant to be used in each? i.e, ambient-go-sdk for the backend, ambient-ts-sdk for the frontend, ambient-python-sdk for various scripting tasks.

does an SDK include a strongly typed Kube client instead of unstructured.Unstructured for easier backend development?

The description includes reference to a "rest frontend" that does exist now. Is the intent of ambient-sdk to work exclusively with that public API?