Decide what users can ask the agent to do, where trusted configuration belongs, and how your application will handle incomplete or failed work. Make those rules explicit across the application and the agent workflow.
This path is an orientation for developers and technical reviewers. Use the linked documentation for exact SDK types, configuration, and implementation steps.
Make the integration decisions explicit
Before implementation, identify the deployment surface, the user journey, the information that crosses each boundary, and the owner of each credential. Define what counts as completion from the application's perspective. A message appearing in the interface and a requested external action completing are different events.
Use the architecture explainer to align the team on concepts, and the permissions guide to review authority.
Follow the canonical documentation
Scroll horizontally to see all columns.
| Implementation question | Documentation |
|---|---|
| How do I begin an external-agent integration? | Getting started |
| How should I understand sessions and storage? | Sessions and storage |
| How are conversations and streaming handled? | Conversations and streaming |
| Where do files and generated results fit? | Files and artifacts |
| Which policy and capability concepts apply? | Policy and capabilities |
| How do workspaces relate to the integration? | Workspaces |
Include failures in the application design
Plan what the user sees when access is denied, a request times out, a conversation is interrupted, or an expected result is unavailable. Do not present a successful completion until you have the evidence required by the workflow. Review retry behavior for any action that could create a duplicate external change.
Use the evaluation guide to create integration cases alongside your application tests. Return to the documentation home for current implementation guidance as the integration evolves.
All guides in this topic
- Decide When an External Agent Needs a Workspace: Use a workspace only for capabilities that need durable state, then verify the granted capabilities and runtime readiness before relying on them.
- Embed an Agent with the External Agents SDK: Keep user authentication and assertion signing on your server, then use the SDK client to establish a session and read the agent’s public policy.
- Keep Public References and Bootstrap Credentials Separate: A browser may use an agent’s public reference, but an authenticated server must sign the bootstrap assertion and protect its signing credential.
- Read an External Agent’s Policy Before Building Its UI: Inspect the agent’s public capabilities and limits, then use the values actually negotiated instead of assuming a requested feature is available.
- Sessions, Conversations, Streaming, Files, and Artifacts: Keep session identity, conversation history, streamed events, uploaded files, and agent-produced artifacts distinct throughout an integration.
- Troubleshoot an External-Agent Integration by Boundary: Trace an integration failure through authentication, policy, session, workspace, input, and stream state before changing code or retrying.