From a demo agent to integration with a business system
A demo shows that an agent can act. A production integration must define what it may do, how success is verified and how the process recovers when something fails.
10 min · Reading & exerciseFree lesson · No registration
Design a narrow agent workflow with explicit tool contracts, enforced access, recoverable actions and evidence of the final result.
Before you start
Know how to define success and inspect evidence from lessons 01 and 02. Familiarity with APIs helps, but the lesson explains each integration decision.
01 / Choose a narrow process
Give the agent a task with a visible finish.
Start with a process you can describe, observe and evaluate. A fixed workflow may be enough when the steps are known. An agent adds value when deciding which information to gather or which supported tool to use requires flexibility. More autonomy also adds paths that need to be tested.
Fictional teaching example
Prepare a contractor access request
At our invented company Northstar, the assistant identifies the requester, checks the applicable policy and prepares a 30-day access request for a sponsor to review. Creating a request does not grant access. A separate approval process remains responsible for provisioning.
Definition of done: One request exists for the verified contractor, correct scope and permitted duration; it is awaiting the required sponsor approval; the assistant reports its actual identifier and status.
This is a design exercise with fictional data, not a production case study or a claim about measured performance.
Write the conditions that require clarification or escalation. Missing identity, an unsupported access scope or a conflicting policy should lead to an explicit decision point rather than an improvised action.
02 / Define tool contracts
Make inputs, outputs and failures explicit.
Expose tools for the business operations the assistant needs. A dedicated “create access request” operation is easier to validate and review than unrestricted database access. Document required fields, allowed values and the states a response can represent.
Operation
Contract to define
Evidence returned
Read applicable policy
Verified requester role and permitted source scope.
Policy version, conditions and source identifier.
Prepare access request
Contractor identifier, resource scope, duration and operation key.
Request identifier and pending approval status.
Read request status
Authorized caller and request identifier.
Current state or an explicit not-found result.
Validate structured arguments in application code. Distinguish invalid input, denied access, a temporary failure and an unknown outcome. Give the model enough information to explain the next step without exposing credentials or internal diagnostics to the end user.
03 / Enforce authority
The server decides whether an action is permitted.
Authenticate the caller and check authorization at every operation. Derive identity and tenant scope from trusted session data instead of trusting a model-supplied user identifier. Restrict service credentials to the operations and resources the workflow needs.
For an action requiring approval, show the exact target, scope and arguments to the approver. Bind approval to that operation and revalidate it at execution time. If the agent changes a consequential argument, the earlier approval must not silently authorize the new proposal.
Policy documents, emails and tool responses may contain hostile instructions. Treat them as data and test attempts to redirect the workflow. A prompt that says “obey the policy” does not enforce permissions; authorization, argument validation and action limits belong in the integration layer.
04 / Design for uncertainty
A timeout does not prove that an operation failed.
A server may create the request and lose the response. Repeating the create call blindly can produce duplicates. Generate a stable operation key before the first attempt and have the backend enforce idempotency: the same logical operation returns the existing result instead of creating another request.
When the response disappears
The application records an operation key and calls the create operation.
The response times out, so the result is unknown.
The workflow looks up the operation or retries with the same key, according to the API contract.
It reports success only after a confirmed request identifier and state are available.
Bound retries and use them only for errors the contract identifies as retryable. Stop when access is denied or input is invalid. For a process spanning several systems, record intermediate states and define recovery or compensation steps. There may be no safe automatic rollback for every action.
05 / Make the process observable
Release a workflow you can inspect and stop.
Connect the user request, model version, policy version, tool calls, authorization decisions and business outcome with a trace identifier. Keep logs useful for diagnosis while minimizing sensitive data and applying an appropriate retention policy. A trace should explain why the workflow reached its result.
Evaluate ordinary completion, missing identity, denied access, duplicate execution, stale policy and timeouts after a write. Check the final system state. Include adversarial documents and tool responses that try to redirect the assistant.
A practical rollout can begin with read-only support, then proposal generation, then a limited action workflow with the required approvals. Define the owner, supported scope, timeout and cost limits, alert conditions and a way to disable execution. Expand only when observed results meet the acceptance criteria for the next step.
Your exercise / About 5 minutes
Write a one-page integration contract.
Choose one operation and define the final business state that proves completion.
List the required inputs, the trusted source of identity and the server-side validation rules.
State which actions need approval and what exact proposal is approved.
Describe what happens if the operation times out after a write, including duplicate prevention.
Add one success case, one denied-access case and one unknown-outcome case to your evaluation set.
Review your contract
Ask whether an engineer could implement the operation without guessing its permissions or recovery behavior. “The agent handles errors” is not a contract. Specify the observable states, permitted next actions and evidence needed before reporting completion.
Knowledge check
Sources & further reading
The access-request workflow and exercises are fictional design examples. These primary sources support the architecture, security and verification principles.