Invoke Background Agent
POST/api/background-agents/:id/invoke
Sends a message to the agent on its external platform and starts (or resumes) a conversation.
Conversations are correlated by session_key — a stable identifier you choose for the entity or thread (for example, a ticket ID or a pull request URL). Sending another message with the same session_key resumes the existing conversation; a new key starts a new session.
The agent must be active and synced to the claude-managed-agents or aws-agentcore platform.
Request
Responses
- 200
- 400
- 401
- 404
- 429
- 500
- 502
Message delivered to the agent
Invalid request, agent disabled, unsupported platform, or agent not synced
Authentication required or invalid token
Background agent not found
The agent is over its budget or has reached one of its session or message limits. The message was not delivered; send it again after the number of seconds in Retry-After.
Response Headers
Seconds until the budget or limit's current period ends.
Internal server error
The external platform rejected the message