> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pion/ice/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent
> ICE Agent implementation for establishing peer-to-peer connections
## Overview
The `Agent` represents the ICE agent responsible for gathering candidates, performing connectivity checks, and establishing peer-to-peer connections according to RFC 5245.
## Creating an Agent
### NewAgent (Deprecated)
```go theme={null}
func NewAgent(config *AgentConfig) (*Agent, error)
```
Creates a new Agent using the legacy configuration struct.
Deprecated: Use `NewAgentWithOptions` instead for better flexibility and forward compatibility.
**Parameters:**
Configuration for the agent. See [AgentConfig](/api/agent-config) for details.
**Returns:** `(*Agent, error)`
### NewAgentWithOptions
```go theme={null}
func NewAgentWithOptions(opts ...AgentOption) (*Agent, error)
```
Creates a new Agent using functional options. This is the recommended way to create agents.
**Parameters:**
Variable number of configuration options. See [Agent Options](/api/agent-options) for available options.
**Returns:** `(*Agent, error)`
**Example:**
```go Basic Usage theme={null}
import (
"github.com/pion/ice/v4"
"github.com/pion/stun/v3"
)
// Create agent with STUN server
stunURL, _ := stun.ParseURI("stun:stun.l.google.com:19302")
agent, err := ice.NewAgentWithOptions(
ice.WithUrls([]*stun.URI{stunURL}),
)
if err != nil {
panic(err)
}
defer agent.Close()
```
```go Advanced Configuration theme={null}
// Create agent with multiple options
agent, err := ice.NewAgentWithOptions(
ice.WithUrls([]*stun.URI{stunURL}),
ice.WithPortRange(10000, 20000),
ice.WithNetworkTypes([]ice.NetworkType{
ice.NetworkTypeUDP4,
ice.NetworkTypeUDP6,
}),
ice.WithCandidateTypes([]ice.CandidateType{
ice.CandidateTypeHost,
ice.CandidateTypeServerReflexive,
}),
)
```
## Key Methods
### GatherCandidates
```go theme={null}
func (a *Agent) GatherCandidates() error
```
Starts the candidate gathering process. This discovers available local addresses and queries STUN/TURN servers.
### GetLocalCandidates
```go theme={null}
func (a *Agent) GetLocalCandidates() ([]Candidate, error)
```
Returns all gathered local candidates.
### AddRemoteCandidate
```go theme={null}
func (a *Agent) AddRemoteCandidate(cand Candidate) error
```
Adds a remote candidate received from the peer. This triggers connectivity checks for candidate pairs.
**Parameters:**
Remote candidate to add. Can be nil (ignored).
### GetSelectedCandidatePair
```go theme={null}
func (a *Agent) GetSelectedCandidatePair() (*CandidatePair, error)
```
Returns the currently selected candidate pair, or nil if no pair is selected.
### SetRemoteCredentials
```go theme={null}
func (a *Agent) SetRemoteCredentials(remoteUfrag, remotePwd string) error
```
Sets the remote agent's ICE credentials.
**Parameters:**
Remote username fragment (must not be empty)
Remote password (must not be empty)
### GetLocalUserCredentials
```go theme={null}
func (a *Agent) GetLocalUserCredentials() (frag string, pwd string, err error)
```
Returns the local ICE credentials (username fragment and password).
### GetRemoteUserCredentials
```go theme={null}
func (a *Agent) GetRemoteUserCredentials() (frag string, pwd string, err error)
```
Returns the remote ICE credentials that have been set via `SetRemoteCredentials`.
### GetRemoteCandidates
```go theme={null}
func (a *Agent) GetRemoteCandidates() ([]Candidate, error)
```
Returns all remote candidates that have been added to the agent.
### Dial
```go theme={null}
func (a *Agent) Dial(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)
```
Connects to the remote agent in controlling mode. Returns a `Conn` that can be used to send and receive data.
**Parameters:**
Context for controlling the dial operation lifetime.
Remote username fragment (from remote agent's GetLocalUserCredentials).
Remote password (from remote agent's GetLocalUserCredentials).
**Returns:** `(*Conn, error)` - Connection for data transfer
**Example:**
```go theme={null}
localUfrag, localPwd, _ := agent.GetLocalUserCredentials()
// Exchange credentials with peer (out of band)
conn, err := agent.Dial(context.Background(), remoteUfrag, remotePwd)
if err != nil {
panic(err)
}
defer conn.Close()
// Use conn for data transfer
_, err = conn.Write([]byte("Hello"))
```
### Accept
```go theme={null}
func (a *Agent) Accept(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)
```
Waits for connection from the remote agent in controlled mode. Returns a `Conn` that can be used to send and receive data.
**Parameters:**
Context for controlling the accept operation lifetime.
Remote username fragment (from remote agent's GetLocalUserCredentials).
Remote password (from remote agent's GetLocalUserCredentials).
**Returns:** `(*Conn, error)` - Connection for data transfer
### Restart
```go theme={null}
func (a *Agent) Restart(ufrag, pwd string) error
```
Restarts the ICE agent with new credentials. If empty strings are provided, the agent generates new credentials.
**Parameters:**
New username fragment. Empty string generates a random value.
New password. Empty string generates a random value.
Credentials must meet minimum entropy requirements: ufrag >= 24 bits, pwd >= 128 bits.
### UpdateOptions
```go theme={null}
func (a *Agent) UpdateOptions(opts ...AgentOption) error
```
Applies options to the agent at runtime. Only a subset of options can be updated after creation (e.g., `WithUrls`).
### Close
```go theme={null}
func (a *Agent) Close() error
```
Cleans up the agent and releases resources. Does not wait for goroutines to complete.
### GracefulClose
```go theme={null}
func (a *Agent) GracefulClose() error
```
Cleans up the agent and waits for all goroutines to complete. Should only be called outside of agent callbacks or in a separate goroutine.
## State Management
### GetGatheringState
```go theme={null}
func (a *Agent) GetGatheringState() (GatheringState, error)
```
Returns the current gathering state. See [GatheringState](/api/gathering-state).
### OnConnectionStateChange
```go theme={null}
func (a *Agent) OnConnectionStateChange(f func(ConnectionState))
```
Registers a handler that is called when the connection state changes.
### OnSelectedCandidatePairChange
```go theme={null}
func (a *Agent) OnSelectedCandidatePairChange(f func(Candidate, Candidate))
```
Registers a handler called when the selected candidate pair changes.
### OnCandidate
```go theme={null}
func (a *Agent) OnCandidate(f func(Candidate))
```
Registers a handler called when a new local candidate is gathered. Called with nil when gathering is complete.
## Renomination
### RenominateCandidate
```go theme={null}
func (a *Agent) RenominateCandidate(local, remote Candidate) error
```
Allows the controlling agent to nominate a new candidate pair. Requires renomination to be enabled.
**Returns:** Error if agent is not controlling, renomination is disabled, or candidate pair not found.
## Type Definition
```go theme={null}
type Agent struct {
// Internal fields (not directly accessible)
}
```
## Related Types
* [AgentConfig](/api/agent-config) - Legacy configuration struct
* [AgentOption](/api/agent-options) - Functional options for agent creation
* [ConnectionState](/api/connection-state) - Connection state enum
* [GatheringState](/api/gathering-state) - Gathering state enum
* [Candidate](/api/candidate-types) - Candidate interface