Plan an integration

Start with one job#

Write down the customer’s request, the result they need and the point where a person should step in. Keep the first workflow small enough to inspect from the incoming message to the final record.

This is a planning guide. A connection still needs an implemented adapter, environment configuration and verification. The API reference describes platform contracts; it does not imply a ready-made connector for every business system.

Map information to its source#

Your business system remains the authority for its records. Use current records for changing facts and reviewed knowledge for the policies it can support. Keep these different kinds of evidence distinct.

Separate reads from actions#

List each operation the workflow needs, its input, its output and who may invoke it. Reading a record does not imply permission to modify it. Workspace API scopes and the agent’s business capabilities are separate boundaries; configure both for the intended job.

Keep API keys on your server and use the assigned environment. Begin with a read-only path. Add an action only when its authority and result can be tested.

Plan for an uncertain result#

A timeout can mean that an operation did not start, completed, or remains unresolved. Do not translate it into a success confirmation or immediately create a new request. Preserve the request identity and inspect the recorded state.

Use the endpoint’s documented idempotency contract when retrying. For a submitted message, inspect the conversation and turns to follow processing. HTTP 202 means the input was accepted; it does not prove an external action or a delivered reply.

Review the whole workflow#

Before widening the pilot, exercise the request with the business owner and the people who handle exceptions. Verify the business record as well as the conversation.