Files
go-sip/proto

Agent Unary gRPC contract

proto/agent/agent.proto is the project-owned Agent/Dispatcher protocol. It is not the SaaS/MQ contract and is not evidence of external supplier acceptance. Both processes use Unary gRPC over mutually authenticated TLS; no audio bytes or SaaS business requests are carried over these RPCs.

AgentControlService exposes only these methods:

  • GetAgentStatus and ActivateAgent probe a deployed Agent and establish its active Dispatcher-bound session. Boot ID, epoch, generation, peer certificate and approved identity fence stale or self-reported callers.
  • GetLoadedSIP reads the Agent's observed trunk revisions. A Mock observation is not proof that Asterisk actually loaded the configuration.
  • ExecuteApproved receives a frozen task/SIP/AI decision and exclusive dial deadline. The Agent checks the session and signed execution boundary, not the Dispatcher's outbound business policy. Unknown execution is never originated again just because an RPC response was lost.
  • ApplyApprovedTaskControl closes task admission before draining or hanging up active calls. Pause, resume and stop carry no external command ID or revision CAS; stop is irreversible for the same task identity.
  • RequestRecordingUpload, ReportCallEnded and ReportCallResult request a bounded upload grant, release a confirmed-ended call and deliver its one final result. The Agent uploads directly to OSS. The RPC never transfers the recording bytes or reports SaaS application receipt.

Task and provider snapshots can contain credentials. Do not log or persist raw request bodies. RequestMeta.protocol_version=agent.v1 is a meaningful wire protocol value, not an implementation-generation label; field numbers are not reused. Errors, unknown outcomes and recovery boundaries are in ERRORS.md.

Generate and verify using the pinned local tools:

buf lint
buf generate
sh scripts/check-proto.sh

The currently registered Agent command supports isolated Mock only. The local mTLS and Mock tests do not establish real Asterisk, OSS, AI or SaaS acceptance.