Skip to main content

3. Introduction to agents

When you have a canister running, either locally or on the mainnet, you have two primary ways for interacting with the canister: using the API through an agent, or using the canister's HTTP interface. On the Internet Computer, an agent is a library used to make calls to ICP's public interface.

What does an agent do?​

Structuring data​

One of the first responsibilities of an agent is to structure data. As was discussed in previous modules, such as 2. Advanced canister calls, calls to ICP can be an update or a query call. An agent submits a POST request to the canister's API at the URL /api/v2/canister/<effective_canister_id>/call. This post request contains the following components:

  • request_type.
  • Authentication, comprised of the sender, nonce, and ingress_expiry.
  • canister_id.
  • method_name.
  • request_id, which is required for update calls. The request_id value is the result of hashing the other fields in the request, and is used for polling while ICP reaches consensus on the update call. Polling is a technique used to check for fresh data over a given interval of time by making repeated API requests to a server.
  • arg, which contains the rest of the call's payload. The agent assembles the arg portion of the call with data from the client application, ensuring that the Candid interface matches the method that it calls.

Each of these components are assembled into a certificate, which is then transformed into a CBOR-encoded buffer. The agent takes this CBOR-encoded certificate and attaches it to the body of the POST request. When the canister begins to process the request asynchronously, the agent begins polling the read_status requests until the canister returns a response.

The agent takes the CBOR-encoded certificate and attaches it to the body of the POST request. The canister will work on that request asynchronously, and then the agent can begin polling with read_state requests, until the canister response is ready.

Decoding data​

Once a response has been returned from the mainnet, the agent takes the certificate from the call's payload and verifies it. This certificate can be verified using the public root key of ICP's NNS subnet. The network will return a CBOR-encoded buffer for the agent to decode, then transform into a useful structure using semantic language-specific types. For example, if the canister returns a type Text, and the agent is a JavaScript agent, the text will get turned into a JavaScript string.

Managing authentication​

Each call to the Internet Computer mainnet needs to have a cryptographic identity attached to the call. This identity can be anonymous or authenticated using a cryptographic signature. Canisters use a call's attached identity to determine how to respond to the call, which enables smart contracts to use identities for other purposes as well.

Accepted identities​

The following types of signatures in identities can be attached to calls to ICP:

  • Ed25519 and ECDSA signatures.
    • Plain signatures are supported for the schemes.
  • Ed25519 or ECDSA on curve P-256 (also known as secp256r1).
    • Using SHA-256 as a hash function.
    • Using the Koblitz curve in secp256k1.

When an agent encodes these identities as a principal, they attach a suffix byte which indicates whether the identity is anonymous or self-authenticating. An anonymous identity will use a suffix byte of 4, which resolves to 2vxsx-fae, while self-authenticating identities that uses one of the curves above uses a suffix of 2.

Available agents​

Currently, there are two agents developed by DFINITY: the JavaScript/TypeScript agent, and the Rust agent.

Additionally, there are several community-supported agents, including: